To define a Protection, create a Prodvana config file.

protection:
  name: is-not-weekend
  taskConfig:
    program:
      cmd:
      - deployment-schedule-validator.py
      imageTag: 3.10.3-slim
      imageRegistryInfo:
        containerRegistry: dockerhub-public
        imageRepository: python

Apply the config file using pvnctl.

pvnctl configs apply path/to/is-not-weekend.pvn.yaml

It is also possible to define a Protection using Kubernetes configs, such as a Kubernetes job.

protection:
  name: is-not-weekend
  kubernetesConfig:
    type: KUBERNETES  # KUSTOMIZE also supported
    local:
      path: .  # change this accordingly

The exit code of a Protection determines what happens in the convergence it is protecting.

Parametrizing Protections

Defining parameters for Protection allow you to define a Protection once but instantiate it multiple times with slightly different inputs. Once defined, parameters value are available as {{.Params.myParamName}} anywhere in the config, including Kubernetes configs.

protection:
  name: is-not-weekend
  taskConfig:
    program:
      cmd:
      - deployment-schedule-validator.py
      - --schedule={{.Params.schedule}}
      imageTag: 3.10.3-slim
      imageRegistryInfo:
        containerRegistry: dockerhub-public
        imageRepository: python
  parameters:
  - name: schedule
    string:
      defaultValue: five-days-work-week

Using a Protection

Using a Protection on a Release Channel

To attach a Protection to a Release Channel, add the following to the Application configuration.

application:
  name: my-application
  releaseChannels:
    - name: my-release-channel
      ...
      protections:
        - ref:
            name: my-protection
            parameters:
            - name: my-param
              string: my-param-value

Run pvnctl configs apply on the Application configuration and the Protection will now show up in the Release Channel page, under my-demo-organization.runprodvana.com -> Applications -> your Application -> your Release Channel.

As defined above, the Protection is purely informative. To have use Protections as part of convergence, add a lifecycle config to the Release Channel's application config.

application:
  name: my-application
  releaseChannels:
    - name: my-release-channel
      ...
      protections:
        - ref:
            name: my-protection
          lifecycle:
            - preApproval: {}
            - postApproval: {}
            - postDeployment:
            	  checkDuration: 120s

The config above tells Prodvana to check the result of the protection before and after approvals are submitted and for 120 seconds after the deployment has been completed.

Using a Protection on a Service Instance

Attaching a Protection to a Service Instance can be done via the Service config file or the Application config file (at which point all Service Instances in that Release Channel gets the Protection).

To add a Protection to a specific Service Instance:

service:
  name: my-service
  application: my-application
  perReleaseChannel:
  - releaseChannel: my-release-channel
    protections:
    - ref:
        name: my-protection
      # optional, if specified, the protection will be used to gate convergence lifecycles
      # of the service (e.g. prevent a service from being deployed if protection is failing)
      lifecycle:
        - preApproval: {}
        - postApproval: {}
        - postDeployment:
            checkDuration: 120s

Run pvnctl configs apply on the config file then go and deploy the Service to activate the Protections.

To add a Protection to all Service Instances in a Release Channel, update the Application config:

application:
  name: my-application
  releaseChannels:
    - name: my-release-channel
      ...
      serviceInstanceProtections:
        - ref:
            name: my-protection
            parameters:
            - name: my-param
              value: my-param-value
          lifecycle:
            - preApproval: {}
            - postApproval: {}
            - postDeployment:
            		checkDuration: 120s

Run pvnctl configs apply on the config file, and all Services will automatically pick up the new Protection on their next deployments.

Using a Protection on a Convergence

Protections should be attached to a convergence when it is verifying something specific to the incoming change (say, a database migration that depends on the code version being pushed).

Convergence-level Protections can be added at different levels. For example, add a convergence Protection to a Release Channel in an Application if it needs to be applied to every Service Instance in this Release Channel.

To attach a Protection to a convergence, add the following to the Application configuration.

application:
  name: my-application
  releaseChannels:
    - name: my-release-channel
      policy:
        defaultEnv:
          ENV_VAR_NAME:
            value: env-var-value
      convergenceProtections:
        - ref:
            name: my-protection
            parameters:
            - name: my-param
              value: my-param-value
          lifecycle:
            - preApproval: {}

Run pvnctl configs apply on the application config and the protection will get created the next time a service is released which includes this release channel.

Valid Lifecycles

Injected Environment Variables

Once Protections are attached to an object, the relevant environment variables identifying the object is injected into programs in the protection, both for protections defined using taskConfig and kubernetesConfig.

Common Examples

Using a Protection to Prevent a Deployment

To have a Protection prevent a deployment from happening, add it to the deployment lifecycle with failureBehavior set to BLOCK. This will cause Prodvana to go through the pre-deployment checks as before, including asking for any approvals, but Prodvana will not apply changes until the Protection passes. This works for any kind of Protection, including Release Channel, Service Instance, and convergence Protections.

application:
  name: my-application
  releaseChannels:
    - name: my-release-channel
      policy:
        defaultEnv:
          ENV_VAR_NAME:
            value: env-var-value
      protections:
        - ref:
            name: my-protection
            parameters:
            - name: my-param
              value: my-param-value
          lifecycle:
            - deployment:
                failureBehavior: BLOCK