Canary OKE Deployment

Create deployment pipeline using Canary release strategy for Container Engine for Kubernetes (OKE).

Prerequisites

Before you create the pipeline, you need these things:

  • Have a DevOps project, Kubernetes cluster environment to deploy to, and artifacts. Artifacts can be defined inline or located in the Artifact Registry.
    Note

    DevOps deployment pipelines currently do not support deployment to OKE clusters with Helm.
  • As the OKE cluster doesn't have an ingress controller by default, an NGINX ingress controller has to be set up for the Canary deployment strategy. An ingress controller is a Kubernetes application that routes traffic based on ingress specification. The NGINX ingress controller monitors ingress resources for load balancing. The traffic is shifted from staging to the production environment by updating the ingress resource. For more information, see Setting Up an Ingress Controller on a Cluster.

Required IAM Policy

Each service in Oracle Cloud Infrastructure (OCI) integrates with Identity and Access Management (IAM) for authentication and authorization. To grant users permission to access the DevOps deployment pipelines and other resources, you have to create dynamic groups and IAM policies.

For creating dynamic groups and policies for deployment pipelines, see Deployment Pipeline Policies. For more details, see DevOps IAM Policies.

For accessing DevOps using the Oracle Cloud Console, REST API, and CLI, see Accessing DevOps.

Using the Console

  1. Open the navigation menu and click Developer Services. Under DevOps, click Projects.
  2. Select a project, and click Create pipeline.
  3. Enter a name and optional description for the pipeline.
  4. For Pipeline type, select Create a deployment pipeline.
  5. Click Create pipeline.
  6. To add a stage to the pipeline, click the + icon and select Add stage.
  7. For stage type, select Canary Strategy, and then click Next.
  8. Select OKE for deployment type.
  9. Enter a name and optional description for the stage.
  10. For Environment, select an existing cluster environment where the canary traffic is shifted.
  11. Enter Canary namespace. For example, canary-env.

    The namespace is used to define the canary deployment environment in the OKE cluster.

  12. Click Select Artifact, and then select one or more artifact resources from your DevOps project.

    The DevOps service performs a Kubernetes server-side apply of the Kubernetes manifest artifacts in the order that they appear in the Console. You can also remove artifacts to select another one or reorder the artifacts list. Removing an artifact in the pipeline stage does not delete the artifact resource from your project. For more information on Kubernetes server-side apply, see Server-Side Apply.

  13. Enter the NGINX ingress name. For example, ingress-nginx.

    This is the name of your application’s ingress resource. DevOps service modifies the annotation on this ingress resource to accomplish the deployment strategy.

  14. Click Next.
  15. You can opt to validate the deployment run or choose not to validate by selecting None.

    To validate the application, a custom function is added to the pipeline. Select Run a custom logic through a function. Enter the following values:

    1. Enter a name and optional description for the stage.
    2. For Environment, select an existing function to invoke.

      The read-only Function name field displays the function that is called in the pipeline.

    3. (Optional) To select and add artifacts to the stage, click Select Artifact.

      Select an existing artifact resource from your DevOps project. The artifact must be generic (universal) file type. Parameters in the artifact must be in JSON format and can have placeholders. You must select the "Yes, substitute placeholders" option when configuring the DevOps artifact resource to substitute the placeholders with the argument value during deployment. For more information, see Configuring Parameters.

      Here's an example of the generic artifact content to pass two user-defined parameters and their values:
      • Parameters: test_name, app_version
      • Values: {"test_name":"verify_production", "app_version":"${app_version}"}
    4. For Stage run mode, select to run asynchronously or synchronously.

      If you select Run asynchronously, the service invokes the function but does not wait for the function to complete. On selecting Run synchronously, the service invokes the function and waits for the function to complete.

    5. Select to disable or enable validation.

      If the validation is enabled, then the service verifies the return value of the function. The return value is a UTF-8 string literal, true or false. If the return value is true, then the stage is marked as Succeeded, otherwise the stage is marked as Failed.

      If the validation is disabled, then the service does not verify the return value.

      Validation occurs only if you have selected the option “Run synchronously” for stage run mode.

    6. (Optional) To add tags to the pipeline, click Show tagging options. Tagging is a metadata system that lets you organize and track the resources in your tenancy.

      You can select a tag namespace or a free-form tag is added. Enter corresponding tag key and tag value. You can add multiple tags.

  16. Click Next.
  17. Enter a name and optional description for the Shift traffic stage to shift part of the traffic to the canary environment.
  18. Enter Ramp Limit in percentage to specify the maximum traffic to be shifted. The value must be between 1 and 25.

    For example, if the ramp limit is 20, then 20% of the traffic is shifted to the canary environment.

  19. Click Next.
  20. Enter a name and optional description for the manual Approval stage.
  21. Enter number of approvers and click Next.
  22. Enter a name and optional description for the Production canary stage.
  23. For Production environment, select an existing cluster environment that is used to deploy the application validated in the canary environment.
  24. Enter the Production namespace.
  25. To automatically roll back the deployment to the last successful version if the stage fails, select the Auto rollback check box.
  26. (Optional) To add tags to the pipeline, click Show tagging options. Tagging is a metadata system that lets you organize and track the resources in your tenancy.

    For more information, see Resource Tags.

  27. To add the stage to the pipeline, click Add.
  28. A modal window opens displaying status of various stage configurations that are part of the OKE canary deployment strategy. They include, canary deployment, traffic shift, approval, and production deployment stages. If the validation is not successful, then you can check the error message specific to each failed stage and take corrective action.

    If the validation is successful, then you can run the deployment pipeline or add more stages sequentially or in parallel to the pipeline, as needed.

Note

For the first canary OKE deployment, you will encounter a "service temporarily unavailable" error message during the deployment run, after the application is deployed to the canary environment. This is an expected behavior, as the ingress resource in the production environment does not exist yet. You can ignore this message and go ahead with the deployment as the error is resolved in the production stage.

Using the CLI

To create a deployment pipeline, run the create command:

oci devops deploy-pipeline create --project-id

To create an OKE canary stage, run the create-deploy-oke-canary-stage command:

oci devops deploy-stage create-deploy-oke-canary-stage

Required parameters:

  • --canary-strategy
  • --kubernetes-manifest-artifact-ids
  • --oke-cluster-environment-id
  • --pipeline-id
  • --stage-predecessor-collection

To get help for this command:

oci devops deploy-stage create-oke-canary-stage -h

To create an invoke function stage, run the create-invoke-function-stage command:

oci devops deploy-stage create-invoke-function-stage

Required parameters:

  • --function-environment-id
  • --is-async
  • --is-validation-enabled
  • --pipeline-id
  • --stage-predecessor-collection

To get help for this command:

oci devops deploy-stage create-invoke-function-stage -h

To create a manual approval stage, run the create-manual-approval-stage command:

oci devops deploy-stage create-manual-approval-stage

Required parameters:

  • --approval-policy
  • --pipeline-id
  • --stage-predecessor-collection

To get help for this command:

oci devops deploy-stage create-manual-approval-stage -h

To create an OKE canary approval stage, run the create-oke-canary-approval-stage command:

oci devops deploy-stage create-oke-canary-approval-stage

Required parameters:

  • --oke-canary-traffic-shift-stage-id
  • --approval-policy
  • --pipeline-id
  • --stage-predecessor-collection

To get help for this command:

oci devops deploy-stage create-oke-canary-approval-stage -h

To get all the commands for deploy-pipeline and deploy-stage:

oci devops deploy-pipeline -h
oci devops deploy-stage -h

Using the API

To create a deployment pipeline, use the CreateDeployPipeline operation.

To create a stage, use the CreateDeployStage operation. Depending on what stages that you want to add to the pipeline, select the following values for stage type:

  • Container Engine for Kubernetes (OKE) canary deployment stage: OKE_CANARY_DEPLOYMENT
  • Invoke function stage: INVOKE_FUNCTION
  • OKE canary traffic shift stage: OKE_CANARY_TRAFFIC_SHIFT
  • OKE canary approval stage: OKE_CANARY_APPROVAL