Onboard your Application
In order for your team to develop or test code against isolated, production-like environments, you'll likely need to onboard a collection of Velocity Services that make up a given application flow.
This guide will help you to onboard such a collection of services as efficiently as possible.
The following diagram illustrates the suggested process for onboarding each service within your application.
- 1.Annotate YAML manifests with Velocity annotations and Dynamic Environment Variables: Use Velocity Annotations and Velocity Templates to make your configuration suitable for repeatable ephemeral environments.
- 2.Validate files with dry run: Use
veloctl env createwith the--dry-runand--fileflags to validate the creation of an environment from your updated manifests. Best practices: - 3.Fix the errors and re-iterate: If
--dry-runfails, follow its error messages and fix your manifests. - 4.Create a test environment: After
--dry-runsucceeds, create an ephemeral test environment from your files without using the--dry-runflag. - 5.Validate run time: Track the environment's deployment status, and fix the configuration if needed. You can use
veloctl env logsto view logs and identify problems. - 6.Commit and move forward: Use
veloctl blueprint committo commit your updated manifests to Velocity, and move to the next service.
In order to allow Velocity environments to be repeatable and to be spun up in parallel, environment variables need to be dynamically defined in your blueprint.
When using Helm, it is best practice to create a values file for Velocity with the dynamic values of the environment variables.
In order to isolate a data flow to onboard, you'll first need to identify a development candidate, i.e., a specific micro-service or module within your application that you want to develop or debug.
While your development candidate could be any micro-service within your application, you may wish to consider the number of additional services it depends on. For example, the development candidate in the below diagram depends on three additional services.
To make early iterations of your onboarding more efficient, you may wish to onboard a development candidate with relatively few dependencies.
Data flows within an application end somewhere. Oftentimes they end at a database, but regardless of the type of service, the end of an application flow is the ideal starting point for onboarding a given flow to Velocity.
Services at the end of the application flow generally don't connect to any other services, nor do they rely on other services being in a ready state in order to run. For example, a database accepts connections from other services but doesn't connect to anything itself.
Because of this, onboarding such services as databases into Velocity requires very few, if any, changes to your original K8s definitions of such deployments. This makes them a great starting point for onboarding a given data flow within your application, as you will be able to deploy a valid environment almost immediately.
Next, you will onboard Velocity Services that depend directly on the database. For example, if we were onboarding the app depicted in the above diagram, after onboarding the database, we would then onboard Dependency 2.
To do so, we will need to annotate the K8s definitions associated with this Velocity Service with Velocity Annotations and Templates.
Once we have done so, we will then be able to onboard the next upstream Velocity Service -- i.e., Dependency 1 in the above diagram.
You can add Velocity Annotations to your existing K8s or Helm source files because they are added under the standard
metadata.annotationstag and do not interfere with deploying these same files to staging or production environments.It is a best practice to write Velocity Template definitions in a dedicated Helm Values file for Velocity, or in a Kustomize overlay, because you don't need Velocity annotations in environments outside of Velocity, such as production or staging, and values or overlay files make this easily configurable.
The Velocity CLI accepts a
--dry-run flag, which can be very helpful in validating any changes you need to make to your original K8s manifests and Helm charts. Depending on your development use case, the development candidate may require data to have been ingested into one or more databases within your development environment. Generally speaking, this is normally done after Velocity annotations and templates have been added to the relevant Velocity Services.