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.
Velocity Annotations: The annotations are added to your K8s entity definitions under the metadata.annotations tag using the following syntax:{directive}. They add essential information about your application.
Velocity Annotations are ignored by other systems and only affect Velocity.
Velocity Templates: 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.

Example of a k8s entity with Velocity Annotations and Templates:

apiVersion: apps/v1
kind: Deployment
name: backend
annotations: backend # Service Identifier mysql # Service Dependency
- name: backend
value: '{velocity.v1:mysql.exposures(port=mysqlport).uri}'

Velocity Services

A Velocity Service represents a standalone application or micro-service deployed in your Velocity environment. It can be comprised of a single k8s resource defintion, but most often it will be comprised of a collection of interrelated Kubernetes resource definitions, such as a deployment, k8s service, ingress, secrets and more.
Your Velocity Blueprint (i.e., your augmented k8s resource defintions or Helm Chart) defines Velocity Services, with their dependencies and required configuration.
Velocity Services are created in one of two ways:
Auto-detected Velocity Services
Kubernetes Jobs and Deployments are automatically designated as Velocity Services.
Kubernetes Jobs exist as Velocity Services independently.
Kubernetes Deployments are automatically merged with the following, related k8s resources, which are then designated together as a single Velocity Service:
  • Config Maps (specified in the Deployment's env or envFrom tags)
  • Secrets (specified in the Deployment's env or envFrom tags)
  • k8s Services (defined by the Deployment's Service selector)
  • Ingress (defined by the Deployment's Service port)
NOTE: While auto-detected services do not need a Velocity Service Identifier, they still require Velocity annotations and templates to define their various dependencies and to incorporate dynamically-generated values, such as entity names and connectivity & configuration details.
User-defined Velocity Services
You can also create Velocity Services from other first-class resource definitions by adding a Velocity Service Identifier annotation to the metadata.annotations portion of the resource definition.
For example, cloud resource CRDs (such as AWS S3 bucket, SQS and other similar resource definitions), are not standard k8s resources, but they are seen and treated as first-class entities, which means that they can be designated as Velocity Services with the addition of a Velocity Service Identifier.
User-defined Velocity Services, like auto-detected Velocity Services, will likely require additional Velocity Annotations and Templates to incorporate dynamically-generated values and connectivity & configuration details.

Velocity service identifier

User-defined Velocity Services require a Velocity Service Identifier.
The Velocity Service Identifier sets the name of the service in Velocity, and allows other Velocity Services to reference it, along with any values defined within it, such as ports and entity names, for example.
The identifier is set on the Kubernetes resource's metadata.annotations using the following annotation format: {value}.
For example:
kind: StorageBucket
annotations: bucket


In Velocity, you can define dependencies between Velocity Services.
Dependencies are used to build a dependency map that helps provision the environment correctly.
Dependencies are optional and only needed for the use cases mentioned below.
Common use cases for dependencies:
  1. 1.
    Defining the environment provisioning order.
  2. 2.
    When creating a new environment, dependent services are automatically added to guarantee environment completeness.
  3. 3.
    Using Velocity Templates to build connection strings and other environment variables dynamically.
The dependencies are defined by adding with a comma-separated list of velocity identifiers (defined by the annotation) of the dependent services.
For example:
apiVersion: apps/v1
kind: Deployment
name: backend-deployment
annotations: backend mysql, postgres # Dependency
apiVersion: apps/v1
kind: Deployment
name: mysql
annotations: mysql
apiVersion: apps/v1
kind: Deployment
name: postgres
annotations: postgres