Search
⌃K

Adding Velocity Services

This guide shows you how to add a new Velocity Service to an existing Velocity Blueprint. We start with a Blueprint that contains a single, working Velocity Service, and then we walk through adding another Velocity Service to the Blueprint, and verifying that it works.

1. Start with your existing, working blueprint

We already have an existing Velocity Service service-a in our Velocity Blueprint, and we want to add another service called backend. In this example, we'll use original-service-a.yaml as our existing Velocity Service.
To view the existing Velocity Service, use the --dry-run flag as follows:
veloctl env create -f https://raw.githubusercontent.com/techvelocity/velocity-blueprints/main/examples/original-service-a.yaml --dry-run
And you should see the following output:
Requesting the creation of environment crazy-flying-dutchman with services at 2022-09-20 18:10:52 IDT...
Velocity Resources
Kind Name Validation Depends On
Velocity Service service-a Valid
├─ Deployment.apps service-a Valid
└─ Service service-a Valid

2. Create a new Velocity Service

Next, we'll create a new Velocity Service called backend that will depend on our existing Velocity Service shown above. It will consist of two K8s objects, a Deployment and a K8s Service.
K8s Deployment
K8s Service
---
apiVersion: apps/v1
kind: Deployment
metadata:
annotations:
velocity.tech.v1/id: backend # Velocity service identifier
name: backend
labels:
app: backend
spec:
selector:
matchLabels:
app: backend
replicas: 1
template:
metadata:
labels:
app: backend
spec:
containers:
- name: backend
image: yeasy/simple-web:latest
imagePullPolicy: IfNotPresent
ports:
- name: c-http
containerPort: 80
env:
- name: SPECIAL_DATA
value: constant-value
---
apiVersion: v1
kind: Service
metadata:
name: backend
spec:
type: ClusterIP
ports:
- port: 8035
targetPort: c-http
protocol: TCP
name: svc-http
selector:
app: backend
Notice the following:
  • The K8s annotation velocity.tech.v1/id: backend declares the backend Deployment as a Velocity Service. Refer to Blueprints Concepts for details.
  • We recommend naming the container ports (e.g - name: c-http ) in the Deployment above. This will enable you to reference it by name from the Kubernetes Service.
  • Again, as shown in the K8s Service above, name the Service port (so that we can refer to it by name from the ingress rather than by port number).

3. Add `backend` as a dependency of our existing Velocity Service

Next, we'll need to add a Velocity dependsOn annotation to our existing Velocity Service, so that it will be able to dynamically reference our backend Velocity Service's exposures such as host and port names dynamically.
apiVersion: apps/v1
kind: Deployment
metadata:
annotations:
velocity.tech.v1/id: service-a # Velocity service identifier
velocity.tech.v1/dependsOn: backend # Add this line to our existing Velocity Service's Deployment definition.
name: service-a
NOTE: You can see the full YAML manifest for both Velocity Services here.
Validate the configuration:
Again, we can use the --dry-run flag to validate our configuration, like so:
veloctl env create \
-f https://raw.githubusercontent.com/techvelocity/velocity-blueprints/main/examples/add-new-service.yaml --dry-run
And we should see the following output:
Requesting the creation of environment lazy-the-hood with services at 2022-09-21 20:52:47 IDT...
Velocity Resources
Kind Name Validation Depends On
Velocity Service backend Valid
├─ Service backend Valid
└─ Deployment.apps backend Valid
Velocity Service service-a Valid backend
├─ Deployment.apps service-a Valid backend
└─ Service service-a Valid

4. (Optional) Expose the new service to the outside world

If your Velocity Service requires HTTPS access via a web browser, you can configure that by adding an annotated K8s Ingress object like the one shown below:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: backend
spec:
rules:
- host: "backend-{velocity.v1.domainSuffix}"
http:
paths:
- backend:
service:
name: backend
port:
name: svc-http
path: /
pathType: Prefix
tls:
- hosts:
- "backend-{velocity.v1.domainSuffix}"
secretName: "{velocity.v1.tlsSecretName}"
Notice the following:
We reference the backend Service port by name - name: svc-http.
The {velocity.v1.domainSuffix} template enables DNS to resolve correctly to each developer's Velocity Environment. Refer to the Velocity Templates Global Properties reference for details.
Verify that service is accessible from the outside world
veloctl env create -f https://raw.githubusercontent.com/techvelocity/velocity-blueprints/main/examples/add-new-service-with-public-uri.yaml
Requesting the creation of environment sad-goliath with services at 2022-09-21 21:13:31 IDT...
Environment 'sad-goliath' status:
Point in time: 2022-09-21 21:13:31 IDT
Service Status Version Public URI Tunneled
backend Ready ...simple-web:latest https://backend-sad-goliath.avichai.viron.dev
service-a Ready ...simple-web:latest
Overall status: Ready
┌──────────────────────────────────────────────────────────────────┐
│ Environment Dashboard: https://app.velocitypre.com/e/sad-goliath │
└──────────────────────────────────────────────────────────────────┘
Your environment is ready!
To develop one of your services you can run:
veloctl env develop --env sad-goliath --service <SERVICE> -- <CMD>
  • Notice the Public URI link.
  • Validate that all is well by following the link, and verifying that you get a correct response.

5. Commit your version of the blueprint

Run the following command to commit the the backend Velocity Service to your Blueprint, so that it will be included by default when creating new Velocity Environments:
veloctl blueprint commit -f https://raw.githubusercontent.com/techvelocity/velocity-blueprints/main/examples/add-new-service-with-public-uri.yaml --source backend
Refer to CLI reference for more information about the blueprint commit command.
Learn more about defining Velocity Blueprint Sources here.

Export an existing Velocity Service definition

You can run the velocity env export command for your Velocity Environment, like so:
>>veloctl env export -f service-a.yaml furious-u-foes
Environment 'furious-u-foes' exported to 'service-a.yaml'