Search…
⌃K

Features

In-cluster connectivity

To enable in-cluster communication, Velocity provides a flexible configuration model based on your existing K8s definitions extended with Velocity's Exposures annotation.

The Exposures Annotation

Exposures is an entity that Velocity creates for every Velocity service.
It is generated automatically from your Kubernetes Service Port definition (referencing the defied port number and the port name) and can be extended with application properties such as username, password, and scheme to construct generic URI templates used to connect your Velocity Services.
For example, if your configuration includes an environment variable that points to a static address, it will not be suitable for creating ephemeral environments. Therefore, Velocity allows you to replace it with a generic Velocity Template that will be resolved automatically upon environment provisioning:'{velocity.v1:mysql.exposures(port=mysqlport).uri}'.
The template contains a Port Identifier that tells Velocity which service and port definitions should be used when constructing the URI.

Service Port Identifier

Velocity automatically generates unique referencable Service Port Identifiers (exposure) for each defined service port. The identifiers are presented when running env create with the --dry-run flag and they are based on your Kubernetes port definitions.
  • <port_name> - is used as an identifier if defined in your manifest.
  • <port_number> - is used as an identifier.
In some scenarios when there are name conflicts or port number conflicts, Velocity generates a hash that helps to reference a specific port definition. In these cases, the port identifier will be <port_name>-<hash> or <port_number>-<hash>
To find the generated port_id, run env create with the --dry-run flag.
Connectivity details (Username, Password, and Application Scheme)
To enable Velocity to generate URIs in the form of schema://user:[email protected] you need to explicitly define the application parameters when exposing a port.
This can be done by adding the following Velocity Annotations to your Velocity Service definition:
  1. 1.
    Constant values
velocity.tech.v1/exposures-<port_id>-user: const="username"
velocity.tech.v1/exposures-<port_id>-password: const="password"
velocity.tech.v1/exposures-<port_id>-scheme: const="https"
You can also use a shorthand:
velocity.tech.v1/exposures-<port_id>-user: "username"
velocity.tech.v1/exposures-<port_id>-password: "password"
velocity.tech.v1/exposures-<port_id>-scheme: "https"
2. Values specified using a Kubernetes resource path
velocity.tech.v1/exposures-<port_id>-user: path="<path in k8s resource>"
velocity.tech.v1/exposures-<port_id>-password: path="<path in k8s resource>"
velocity.tech.v1/exposures-<port_id>-scheme: path="<path in k8s resource>"

Auto-generated URI Segments

The Exposures entity automatically generates pre-built parameters that you can use in your configuration. The basic 'host' and 'port' parameters are defined by your Kubernetes Service Port specifications, while complex parameters such as 'URI' combine the 'host' and 'port' with the relevant application properties.
Velocity Template Syntax: {velocity.v1:<id>.exposures(port=<port_id>).<internal_url_segment>}
Auto-generated properties for <internal_url_segment>:
  • uri -> scheme://user:[email protected]:port
  • scheme -> scheme (http, https, etc...)
  • user -> user (the username segment of the exposure)
  • password -> password (the password segment of the exposure)
  • host -> host (service name)
  • port -> port (service port)

In-Cluster Connectivity Example

apiVersion: apps/v1
kind: Deployment
metadata:
name: backend
annotations:
velocity.tech.v1/dependsOn: mysql
velocity.tech.v1/id: backend
spec:
containers:
- name: backend
env:
- name: DB_CONNECTION_STRING
value: '{velocity.v1:mysql.exposures(port=mysqlport).uri}'
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: mysql
annotations:
velocity.tech.v1/id: mysql
velocity.tech.v1/exposures-mysqlport-user: const="username"
velocity.tech.v1/exposures-mysqlport-password: const="password"
velocity.tech.v1/exposures-mysqlport-scheme: const="https"
spec:
containers:
- name: mysql
env:
- name: DATABASE_NAME
value: 'orders'
ports:
- name: mysql
containerPort: 3306
protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
name: mysql
spec:
selector:
app: mysql
ports:
- name: mysqlport
port: 3306
targetPort: mysql
protocol: TCP

External connectivity using K8s Ingress

To enable public access from the internet to your Velocity Services, you can use your existing Kubernetes Ingress definition.
Velocity use your Ingress definition and create an Ingress resource in every new environment created in your cluster.
To make your Ingress definition unique for every environment, Velocity provides the {velocity.v1.domainSuffix}template that generates a different domain suffix for each created environment
Velocity Template
Description
{velocity.v1.domainSuffix}
A combination of the environment name and the domain name in the form of: environmentName.domainName
Please note that using Ingress requires installing an Ingress Controller in your cluster.
External Connectivity Example
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: traefik
traefik.ingress.kubernetes.io/router.entrypoints: websecure
traefik.ingress.kubernetes.io/router.tls: "true"
name: backend-ingress
spec:
rules:
- host: "backend-{velocity.v1.domainSuffix}"
http:
paths:
- backend:
service:
name: viron-backend
port:
number: 80
path: /
pathType: Prefix

External Connectivity using 3rd party CRDs

There are cases where Ingress kinds are replaced by a CRD (take for example Ambassador's Mapping + Host CRDs). For those cases to help Velocity identify the public hostname of a given exposure you can specify the hostname on the main resource (Deployment, Statefulset, Job) manifest using the annotation: velocity.tech.v1/exposures-<port_id>-publicHostname: const="<hostname>".
More over you will need to mark the CRD resources as associated to the relevant Velocity Services (comma seperated ids). This will help Velocity know which resource to include for a given Velocity Service when creating a new environment. You can do it using the annotation: velocity.tech.v1/associateTo. Ambassador mapping example
apiVersion: apps/v1
kind: Deployment
metadata:
name: backend
annotations:
velocity.tech.v1/dependsOn: mysql
velocity.tech.v1/id: backend
velocity.tech.v1/exposures-http-publicHostname: "backend-{velocity.v1.domainSuffix}"
spec:
containers:
- name: backend
---
apiVersion: v1
kind: Service
metadata:
name: backend
spec:
selector:
app: backend
ports:
- name: http
port: 8080
targetPort: 8080
protocol: TCP
---
apiVersion: getambassador.io/v3alpha1
kind: Host
metadata:
name: backend-hostname
annotations:
velocity.tech.v1/associateTo: backend
spec:
hostname: "backend-{velocity.v1.domainSuffix}"
---
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
name: backend-mapping
annotations:
velocity.tech.v1/associateTo: backend
spec:
hostname: "backend-{velocity.v1.domainSuffix}"
prefix: /
service: backend:8080

Random values

In some cases, you might need to generate random strings in your configuration.
A common use case for using random strings is generating passwords, or secured tokens when provisioning new infrastructure resources.
Velocity allows you to use the {velocity.v1.generate:random}Velocity Template which will be resolved into a string upon provisioning. The syntax supports two options:
  1. 1.
    A simple random string that translates into an 8 character string: {velocity.v1.generate:random}
  2. 2.
    A custom regular expression: {velocity.v1.generate:random([a-zA-Z0-9]{8})}
The random generator uses a combination of environment name, environment creation date, resource identifier, and path in the manifest as a seed of the random generator
Example:
apiVersion: apps/v1
kind: Deployment
metadata:
name: mysql
annotations:
velocity.tech.v1/id: mysql
spec:
containers:
- name: mysql
env:
- name: DATABASE_NAME
value: 'orders'
- name: DATABASE_PASSWORD
value: '{velocity.v1.generate:random}'

Auto-generated values

Velocity provides you with auto-generated Velocity Templates that are resolved upon environment provisioning and can help use dynamic values in your environment provisioning.
Velocity Template
Description
{velocity.v1.envName}
The name of the environment For example: angry-hero
{velocity.v1.domainName}
The name of the domain. For example: viron.com
{velocity.v1.domainSuffix}
The full domain suffix for the specific environment. For example: angry-hero.viron.com
{velocity.v1.gcp.projectName}
The GCP project name that is configured for the account. For example: viron
{velocity.v1.gcp.zone}
The GCP zone that is configured for the account.
For example: europe-west2-b
{velocity.v1.aws.accountID}
The AWS account id that is configured for the account. For example: 123456789000
{velocity.v1.aws.region}
The AWS region that is configured for the account. For example: eu-central-1

Service variables

Using variables and referencing them from your services is very powerful. It allows you to initialize the service with values defined during the environment setup. For example: Initiating an environment variable with the connection string of another service.
To use variables, you first need to export them from your source service, as explained below, and then reference them from your target service (see: referencing-exported-variables).
Exporting a variable is done by adding the following annotation to your Velocity Service: velocity.tech.v1/exports-<variable>
The export format supports two options:
A constant value
apiVersion: apps/v1
kind: Deployment
metadata:
name: mysql-database
annotations:
velocity.tech.v1/id: mysql
velocity.tech.v1/exports-db_name: const="orders"
A value specified using a Kubernetes resource path
apiVersion: apps/v1
kind: Deployment
metadata:
name: mysql-database
annotations:
velocity.tech.v1/id: mysql
velocity.tech.v1/exports-db_name: path="spec.template.spec.containers.(name=my-sql).env.[0].value"
spec:
selector:
matchLabels:
app: mysql
template:
metadata:
labels:
app: mysql
spec:
containers:
- name: my-sql
env:
- name: DATABASE
value: 'orders'
To reference an exported variable:
  1. 1.
    Explicitly declare a dependency on the exporting Velocity Service using the velocity.tech.v1/dependsOn annotation.
  2. 2.
    Use the following Velocity Template in the following format to reference the exported variable's value: {velocity.v1:id.exports.variable}
For Example:
apiVersion: apps/v1
kind: Deployment
metadata:
name: backend-deployment
annotations:
velocity.tech.v1/dependsOn: mysql-database
velocity.tech.v1/id: backend
spec:
containers:
- name: backend
env: ya
- name: DATABASE_NAME
value: '{velocity.v1:mysql-database.exports.dbname}'

Environment parameters

Environment parameters are placeholders defined in your Velocity account, allowing users to control their environment provisioning. When creating or updating an environment, the user can set custom values to the predefined parameters and control the environment provisioning.
To use environment parameters, you first need to define them, and then reference them in your K8s resource.
Inject an environment parameter is done by adding the following annotation to your Velocity Service: velocity.v1.param:<param_name>
For Example:
apiVersion: apps/v1
kind: Deployment
metadata:
name: backend-deployment
annotations:
velocity.tech.v1/id: backend
spec:
containers:
- name: backend
env:
- name: TENANT_ID
value: '{velocity.v1.param:tenant_id}'

Kubernetes secrets

In order to use variables in Kubernetes secrets, you can add Secret resources and use them as part of the environment configuration. You can use dependencies in order to populate the secret value dynamically.
For Example:
apiVersion: v1
kind: Secret
metadata:
name: db-credentials
annotations:
velocity.tech.v1/dependsOn: mysql # Velocity dependencies declaration
type: Opaque
stringData:
DB_USER: "{velocity.v1:mysql.exposures(port=mysql).user}"
DB_PASSWORD: "{velocity.v1:mysql.exposures(port=mysql).password}"
Click here for helm usage