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'
Creating a Blueprint
Review a Resolved Blueprint
Last modified 2mo ago