GuidesAPI Reference
Log In

Configuring Applications

To define an application, create a Prodvana config.

application:
  name: my-app # replace with your desired app name
  releaseChannels:
  - name: staging
    runtimes:
    - runtime: my-runtime
  - name: production
    runtimes:
    - runtime: my-other-runtime  # can be the same runtime as the previous step
    preconditions:
    - releaseChannelStable:
        releaseChannel: staging
    - manualApproval: {}
 # add or remove release channels as needed

preconditions control what must be confirmed before services can deploy in that release channel. In the config above, staging must be deployed before production, and a manual approval must be submitted.

Use pvnctl to apply this config file:

pvnctl configs apply path/to/my-app.pvn.yaml

Once applied, you can see your newly created application in my-demo-organization.runprodvana.com -> Applications.

Common Examples

Using an Existing Namespace

Each release channel maps to a namespace in Kubernetes. By default, Prodvana will automatically create and use a namespace of the format pvn-{app}-rc-{release_channel}. To use an already existing namespace instead, set the following in the release channel config as part of the runtimes section:

application:
  name: my-app # replace with your desired app name
  releaseChannels:
  - name: staging
    runtimes:
    - runtime: my-runtime
      containerOrchestration:
        k8s:
          namespace: my-existing-staging-namespace
  - name: production
    runtimes:
    - runtime: my-other-runtime  # can be same or different runtime as previous step
      containerOrchestration:	
        k8s:
          namespace: my-existing-production-namespace
    preconditions:
    - releaseChannelStable:
        releaseChannel: staging
    - manualApproval: {}

🚧

Namespace Must Be Created Outside of Prodvana

If the namespace is explicitly set, you are responsible for ensuring the namespace exists before running pvnctl configs apply, and for deleting it if the release channel is deleted.

If the namespace is not explicitly set, then Prodvana will manage the namespace lifecycle for you automatically.

🚧

Beware of Collisions

Prodvana will allow multiple release channels to be set to the same namespace in the same runtime, both within the same application and across multiple applications. In these cases, you are responsible for making sure the Kubernetes objects do not collide, e.g. by using templated names via constants (see below) or explicitly providing different configs per release channel.

With Metadata

Applications can have metadata like descriptions, application links, and per-service links. This should be included in the same config file.

application:
  ...  # app config here
applicationMetadata:
  description: "description here"
  links:  # application level links
  - url: "http link for your app"
    displayName: "display name"
  serviceLinks:  # links each service gets automatically. variables $application and $service gets substituted with application and service names
  - url: "http link for your service"
    displayName: "display name"

Set Default Env Variables per Release Channel

As part of defining release channels, it is possible to define env variables every service should get. This can be useful for defining variables that should be different per release channel, such as a database address.

application:
  name: my-app
  releaseChannels:
  - name: production
    policy:
      defaultEnv:
        MY_ENV_VAR:
          value: env-var-value
  ... # more release channels here

For Kubernetes and Kustomize configs, Prodvana will automatically try to inject these variables into objects it knows about (at the time of this writing, Deployment, Job, and Argo Rollout are supported).

Defining Constants For Templating

As part of defining release channels, it is possible to define constants that services can reference via templates. This can be useful for release-channel-specific values, not directly derivable from the release channel name, and cannot be passed as environment variables.

application:
  name: my-app
  releaseChannels:
  - name: production
    constants:
    - name: myConstant
      string:
      	value: myValueForProduction
    ... # rest of production config here
  - name: staging
    constants:
    - name: myConstant
      string:
      	value: myValueForStaging
    ... # rest of staging config here

The constant can then be used by services belonging to the application in service configs and external configs such as Kubernetes. Using constants in templating allows most configs to be written once and reused for all release channels without pulling in a complex templating language like kustomize.

service:
  name: my-service
  program:
    cmd: [my-cmd, "--arg={{.Constants.myConstant}}"]
    ...
  ...
service:
  name: my-service
  kubernetesConfig:
    local:
      path: deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 1
  template:
    metadata:
      labels:
        app: nginx
        myLabelFromConstant: "{{.Constants.myConstant}}"
    spec:
      containers:
        - name: nginx
          image: nginx:1.14.2
          ports:
            - containerPort: 80

Defining Shared Approvals Between Release Channels

manualApproval preconditions are scoped to release channels. To define approvals that are shared between release channels (that is, approving one would approve all), use thesharedManualApproval.

application:
  name: my-app
  releaseChannels:
  - name: staging
    runtimes:
    - runtime: my-runtime
  - name: production-1
    runtimes:
    - runtime: my-runtime
    preconditions:
    - releaseChannelStable:
        releaseChannel: staging
    - sharedManualApproval:
        name: production  # name is required and has to match what is defined in other release channels to share approval with
  - name: production-2
    runtimes:
    - runtime: my-runtime
    preconditions:
    - releaseChannelStable:
        releaseChannel: staging
    - sharedManualApproval:
        name: production  # name is required and has to match what is defined in other release channels to share approval with

FAQs

🚧

Removing Release Channels connected to broken runtimes

If a release channel is connected to a broken or disconnected runtime, further updates to the application config will fail until all the broken release channels are removed. Make sure to remove all broken release channels simultaneously.