Configuring Services
To define a service, create a Prodvana config in a directory of your choosing, e.g. if you have an existing directory you use to store other configurations for the service, use that. Prodvana supports a simplified schema for configuring services in a backend agnostic way, as shown below. If you need anything more sophisticated, please define Kubernetes configurations (see below) directly and refer to them from your Prodvana config files.
service:
name: nginx
application: my-application
programs:
# name of the program
- name: program-name
imageRegistryInfo:
# name of the container registry integration (see ${org}.prodvana.io -> Integrations)
containerRegistry: dockerhub-public
# name of the image repository for this registry
imageRepository: library/nginx
imageTag: 1.22-alpine
# (optional) command to run
cmd:
- nginx
- '-g'
- daemon off;
# (optional) replica settings
replicas:
fixed: 5
# set to NONE for now, will undo later
parametersAutogen: NONE
Use pvnctl to apply this config file:
pvnctl configs apply path/to/my-service.pvn.yaml
Once applied, the service will be configured but not deployed. You can see it by going to my-demo-organization.runprodvana.com -> Applications -> your app -> your service.
Deploying from UI
To deploy the service from the service UI, click "deploy" and follow the on-screen instructions.

Parametrizing from UI
You can define parameters in your service config that can then be set at push time in the UI. This is useful for fast changes of safe fields, such as replica count or container image, without going through a code commit.
Additionally, when using Prodvana's simplified schema, Prodvana can automatically define standard parameters, as controlled by autogen_parameters
in your service config. Valid values are:
NONE
- do not automatically generate any parameters.IMAGE
- generate a parameter per program to allow changing the images from the UIIMAGE_AND_REPLICAS
-IMAGE
+ generate a parameter to change the fixed replica count
If unset, the default behavior is IMAGE
.
Below is what the deploy screen looks like with autogen_parameters
set to IMAGE
.

IMAGE_AND_REPLICAS

Custom Parameters
Custom parameters can be defined and then used as go templates under {{.Params.paramName}}
. For example:
service:
name: nginx
application: my-app
programs:
- name: nginx
imageRegistryInfo:
containerRegistry: dockerhub-public
imageRepository: library/nginx
imageTag: 1.22-alpine
env:
ENVIRONMENT:
value: "{{.Params.env}}"
replicas:
fixed: 5
parametersAutogen: IMAGE_AND_REPLICAS
parameters:
- name: env
description: "Environment, used for tagging"
string:
defaultValue: dev

Custom parameters can be used anywhere a string is used.
Template Variables
Template variables are available for service configs and any Kubernetes, Kustomize, or Helm configs they reference. These variables are replaced with their actual values for each release channel. Template variables are referenced using the {{ .SomeVariable.nestedField }}
or {{ .SomeVariable["nestedField"] }}
syntax.
Variable | Value |
---|---|
.Params.<parameter name> , e.g. .Params.image | The parameter value for that release channel |
.Constants.<constant name> , e.g. .Constants.env | The constant value for that release channel. Services inherit constants from release channels but may supply their own override. See "Defining Constants" below. |
.Builtins.ReleaseChannel.Name | The release channel name |
.Builtins.ReleaseChannel.Labels.<label name> , e.g. .Builtins.ReleaseChannel.Labels.env | The label value for the release channel. See Labels. |
.Builtins.Runtime.Name | The runtime name this service runs on for this release channel |
.Builtins.Runtime.Labels.<label name> , e.g. .Builtins.Runtime.Labels.env | The label value for the runtime. See Labels. |
Template variables can be used anywhere a string is expected, with the following exceptions:
local.path
andlocal.excludePatterns
underkubernetesConfig
Common Examples
Using Kubernetes Config
It is possible to use a Kubernetes config with Prodvana instead of the Prodvana runtime-agnostic config above. Kubernetes config is recommended for sophisticated use cases where you need to control specific service behavior, e.g. specific health check behavior, resource constraints, and volume mounts. When using Kubernetes configs, Prodvana will automatically replace the namespace with the namespace of the release channel being deployed. Prodvana will also add additional environment variables (PVN_*
) as well as any environment variables that are set in the release channel config as defaults, as long as it recognizes the Kubernetes objects (deployment
, job
supported today).
service:
name: my-service
kubernetesConfig:
type: KUBERNETES
local:
path: path/to/config/relative/to/this/file # can also be a directory, in which case all yaml files are selected
Parameters can still be used with Kubernetes configs, but they can no longer be automatically generated. Define them explicitly:
service:
name: my-service
kubernetesConfig:
type: KUBERNETES
local:
path: path/to/config/relative/to/this/file # can also be a directory, in which case all yaml files are selected
parameters:
- name: image
required: true
dockerImage:
imageRegistryInfo:
containerRegistry: my-registry-name
imageRepository: my-repository
The template variables should be used directly inside Kubernetes configurations, such as
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment
spec:
replicas: 1
selector:
matchLabels:
app: my-deployment
template:
metadata:
labels:
app: my-deployment
spec:
containers:
- name: api
image: "{{.Params.image}}"
The order of operation is:
pvnctl
reads in your local config file and passes it as a string to Prodvana.- Prodvana sets namespace and injects environment variables.
- Prodvana evaluates and applies template variables.
Templating Kubernetes Config Path
local.path
field under kubernetesConfig
does not support the use of template variables, as pvnctl
uses this value to read your local config files before evaluating variables.
To use template variables in config paths, use path
to specify an overarching directory and use subPath
instead to control which file or directory under path
to read.
service:
name: my-service
application: my-application
kubernetesConfig:
type: KUBERNETES
local:
path: configs
subPath: "{{.Params.myParam}}"
...
In the example above, say the value of myParam
is my-value
, the config being used will be under configs/my-value
.
When subPath
is used:
path
must be a directory- the entirety of
path
is uploaded to Prodvana as a tarball
If the config type is KUSTOMIZE
, pvnctl
will find all kustomization files and run kubectl kustomize
to get the materialized config. This can result in errors if kustomization components are included under path
and cannot be evaluated on their own. To exclude them, use excludePatterns
.
service:
name: my-service
application: my-application
kubernetesConfig:
type: KUSTOMIZE
local:
path: configs
subPath: "{{.Params.myParam}}"
excludePatterns: # follows gitignore convention
- components
Different Kubernetes Config Per Release Channel
If you need to customize Kubernetes configs per release channel beyond namespaces and environment variables, the easiest way is to use template variables with subPath
. For example:
service:
name: my-service
kubernetesConfig:
type: KUBERNETES
local:
path: .
subPath: "{{.Builtins.ReleaseChannel.Name}}"
If needed, you can also explicitly pass a different config per release channel.
service:
name: my-service
application: my-application
perReleaseChannel:
- releaseChannel: staging
kubernetesConfig:
type: KUBERNETES
local:
path: staging-configs/
- releaseChannel: prod
kubernetesConfig:
type: KUBERNETES
local:
path: prod-configs/
perReleaseChannel
acts as an override, so if you have all but one release channel needing a different set of configs, you can also set it as:
service:
name: my-service
kubernetesConfig:
type: KUBERNETES
local:
path: global
perReleaseChannel:
- releaseChannel: staging
kubernetesConfig:
type: KUBERNETES
local:
path: staging-configs/
Using Public Helm Charts
To deploy public Helm charts:
service:
name: kubecost
application: my-app
helm:
remote:
repo: https://kubecost.github.io/cost-analyzer/
chart: kubecost/cost-analyzer
chartVersion: "1.102.2"
Values.yaml can also be specified, like:
service:
name: my-service
application: my-app
helm:
remote: ... # helm chart reference here
valuesOverride:
- local:
path: my-local-values.yaml
- map:
my-value-name:
value: my-value
Values.yaml have access to template variables like parameters, too.
service:
name: my-service
application: my-app
helm:
remote: ... # helm chart reference here
valuesOverride:
- local:
path: my-local-values.yaml # the content of this file can also reference template variables
- map:
my-value-name:
value: my-value
my-image:
value: '{{.Params.myImage}}'
parameters:
- name: myImage
required: true
dockerImage:
imageRegistryInfo:
containerRegistry: my-registry-name
imageRepository: my-repository
Using Local Helm Charts
To use Helm charts defined locally in your own repository (that is, you have a Chart.yaml file):
service:
name: my-service
application: my-app
helm:
local:
path: . # path to directory containing Chart.yaml
valuesOverride: ... # as needed
In this mode, pvnctl configs apply
must be run on a machine with helm
installed. pvnctl
will run helm package
to package your chart into a tarball and upload it to Prodvana.
With Metadata
Services can have metadata like descriptions and links. This should be included in the same config file.
service:
... # service config here
serviceMetadata:
description: "description here"
links:
- url: "http link for your service"
displayName: "display name"
Skipping Cleanup on Deletion
By default, Prodvana will attempt to delete any objects it created (such as, Kubernetes deployments) when a service is deleted. This can be undesirable during the migration period to Prodvana and can be skipped by a flag in the config file:
service:
... # service config here
noCleanupOnDelete: true
Referencing Multiple Kubernetes/Kustomize Configs, Controlling Order
It is possible to reference multiple Kubernetes configs (either in Kubernetes yaml format or Kustomize).
service:
name: my-service
kubernetesConfig:
type: KUBERNETES # or, KUSTOMIZE
local:
paths:
- path/to/config/relative/to/this/file
- path/to/other/config/relative/to/this/file
At pvnctl configs apply
time, the configs are read in order. For directories, all yaml files (except .pvn.yaml files) are read in. The configs are then joined into a single YAML file delimited by ---
.
Currently, mixing and matching Kubernetes configs with Kustomize configs are not supported.
Defining Constants
Constants can be defined and used in service configs to customize the fully materialized configs in each release channel. Constants defined by services override any defined by release channels. See .Configuring Applications.
service:
name: my-service
programs:
cmd: [my-cmd, "--arg={{.Constants.myConstant}}"]
...
...
perReleaseChannel:
- releaseChannel: production
constants:
- name: myConstant
string:
value: myProductionValueForThisService
- releaseChannel: staging
constants:
- name: myConstant
string:
value: myStagingValueForThisService
Constants can also be used in Kubernetes configs directly, the same as parameters.
Adding Environment Variables
Services can have environment variables defined at the service and service instance (release channel, service pair) level. These are different from environment variables defined in program configs for services using Prodvana's backend agnostic config, as this method will work both for the backend agnostic config and external configs such as Kubernetes configs.
Specifying environment variables at the service scope can be helpful for a few use cases:
- overriding release channel default environment variables (see Configuring Applications)
- passing different environment variables per release channel while using a single Kubernetes config file
- injecting environment variables for a Kubernetes config file you do not own or do not want to modify
When environment variables are specified at multiple locations, they given the following precedence (from highest to lowest):
- program-level environment variables (backend agnostic config only)
- per-release-channel environment variables at the service config layer
- top-level environment variables at the service config layer
- environment variables at the application's release channel config layer
service:
name: my-service
env:
MY_ENV:
value: value
perReleaseChannel:
- releaseChannel: staging
env:
MY_OTHER_ENV:
value: staging-value
# the rest of config here, including Kubernetes configs
Disable Automatic Rollbacks
By default, deployments initiated from the Prodvana UI will automatically roll back to the last known converged version when the deployment fails. To disable this behavior, add the following to your service config:
service:
name: my-service
autoRollback:
disabled: true
...
Updated 15 days ago