Annotations and Templates
Annotations and Templates are the Velocity solution for replacing hard-coded values in Kubernetes resource definition files with dynamically-created values, so that the same YAML files you already use can be used to create any number of related, ephemeral development environments.
In order to use your existing k8s/Helm files as a Velocity Blueprint, Kubernetes entity definitions need to be augmented with a combination of Velocity annotations and templates.
The annotations are added to your K8s entity definitions under the metadata.annotations tag using the following syntax:
velocity.tech.v1/{directive}. They add essential information about your application.Velocity Annotations are ignored by other systems and only affect Velocity.
Templates are placeholders that you add anywhere in your k8s entity definitions, which will be interpreted dynamically by Velocity during provisioning. Templates are used to set dynamic values in environment variables or define unique identifiers to cloud resources and more.
It is recommended to keep Velocity Templates in a separate Helm Values file or a Kustomize overlay.
apiVersion: apps/v1
kind: Deployment
metadata:
name: backend
annotations:
velocity.tech.v1/id: backend # Service Identifier
velocity.tech.v1/dependsOn: mysql # Service Dependency
spec:
containers:
- name: backend
env:
- name: DB_CONNECTION_STRING
value: '{velocity.v1:mysql.exposures(port=mysqlport).uri}'
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 |
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:
apiVersion: apps/v1
kind: Deployment
metadata:
name: mysql-database
annotations:
velocity.tech.v1/id: mysql
velocity.tech.v1/exports-db_name: const="orders"
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.Explicitly declare a dependency on the exporting Velocity Service using the
velocity.tech.v1/dependsOnannotation. - 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 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}'
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}"
Last modified 3mo ago