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 UI
• IMAGE_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.

Template variables can be used anywhere a string is expected, with the following exceptions:

• local.path and local.excludePatterns under kubernetesConfig

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:

1. pvnctl reads in your local config file and passes it as a string to Prodvana.
2. Prodvana sets namespace and injects environment variables.
3. 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
  ...