Using Deployment Health Checks In a Rainbow Deployment

• Difficulty - intermediate
• Time To Complete - 20-30 minutes
• Free Tier Compatible - no

Resources

Before starting this guide, several resources are required.

• Server
• Environment
• Hosted DNS Zone
• Stack File

A GitHub repository has been provided with all the necessary resources for following along with this guide.

For those using a custom Stack file, it must meet the following requirements to ensure compatibility with the walkthrough:

• It should define and implement health checks.
• It must utilize an image that is publicly accessible and served over bind-all IPv6.
• The internal server port must be identified.

Creating the Stack

First, import the Stack into Cycle.

1. Navigate to the Stacks tab
2. Click Create in the top left above the Stacks list
3. Add a Stack name
4. Select Import from Git Repo
5. Paste the link from the Git Repo into the Git Repo URL field
6. The Git Repo has the stack file at cycle.json, which is the default, so Stack File field can use the default. If the stack file is named something else, set this field to the name of the Cycle Stack File
7. Click Create Stack

Once the Stack is created, click Create Stack Build in the upper right of the stack to generate a build.

Creating the Deployment

Begin by creating a new deployment from the existing stack build. This step establishes a foundation for the next steps. From here, deployment tags will be created that can be associated with a LINKED Record.

Once the new stack is created, the system will automatically route to it. Click the Deploy button in the upper right corner.

Using the stack deploy modal, select Deployment type. Choose the previously created environment, then enter a pre-1.0 version (e.g., 0.1.0). The rest of the form can be left with default selections. Then, click the Deploy button.

Once the stack is deployed, click on Continue To Environment and start the environment containers. A key advantage of using a stack is that all container configurations are managed within the stack itself, eliminating the need for manual updates. Once the container is running, proceed with creating a tag for the deployment.

To do this:

1. Click on the Deployments tab within the environment
2. Click the + button next to the new deployment.
3. In the popup, add a tag. For this tutorial, use the tag current.

Setting Up Records

Now that the tag is set up, a LINKED Record can be associated with the tag. This allows for an association between a domain and a container within a deployment. This mechanism will facilitate the rainbow deployment via the pipeline.

When the tag is later updated to point to a new deployment, traffic will automatically switch over.

To create the record:

1. Return to the DNS Zone created earlier
2. Click Add Record button in the top right
3. In the Record Create dialog, create a LINKED Record
4. Select the Environment with the Deployment
5. Select Link to Deployment
6. Add the container identifier on left-hand side of the form, and the tag on the right
7. Select TLS Enabled to automatically generate a TLS cert for this domain.
8. Navigate to the domain and a Hello World application should appear

Adding the Pipeline

The next step is to create the Pipeline.

1. Navigate to the Pipelines Section of the Portal
2. Click the Create button
3. Provide a name
4. Select Dynamic pipeline. This allows for variables to be inserted into the pipeline at runtime.
5. Select the Editor tab to add stages and steps.

Pipeline Steps

Step 1: Create Stack Build

The first two steps in this pipeline involve creating and generating the assets (stack build) that will be used.

1. Click on the Add New Step button, then select Create Stack Build from the dropdown menu.
2. Before filling out the Stack portion of the form, add a step reference create at the top of the form.
3. Use the lookup functionality to select the stack from Stack Build Search. Refer to the image below for guidance on locating this in the modal.

The rest of the form can stay use the defaults since the stack refererences the main branch and latest commit.

Step 2: Generate Stack Build

1. Add the step Generate Stack Build from the dropdown menu.
2. Add a step reference generate at the top of the form.
3. In the Stack portion of the form, select From in the Target section and then select (Stage 1) -> create (Step 1) from the dropdown
   • This will use the Stack specified in the previous step and generate a full build of all images to prepare for deployment

Step 3: Deploy Stack Build

1. Add the step Deploy Stack Build.
2. Select the appropriate environment using the environment search feature seen in step 1
3. For the Stack Build location, select From and target (Stage 1) -> generate (Step 2), which is the output from the previous step.
4. Check the deployment box and use {{deployment-version}} for the pipeline variable in the version field.
   • this will allow the variable to be specified at runtime

Step 4: Start Environment Deployment

1. Add the step Start Environment Deployment
2. Select the appropriate Environment
3. Set the version variable to {{deployment-version}} to match the variable specified in the previous step

Once the deployment is started, the next step is wait for the deployment's health check to pass. Only after the health check is successful should the process move on to updating the deployment tags to reflect the new deployment. This ensures that everything is online before the load balancer routes traffic to the new deployment.

Step 5: Wait for Environment Deployment Health Check

1. Add the step Wait for Environment Deployment Health Check
2. Select the Environment
3. Add the version using the variable {{deployment-version}}
4. Optionally, add a duration
   • the default is 5 minutes and is fine for this tutorial

With the health check in place, the pipeline will pause to verify that the deployment is healthy. At this point, traffic can switch over, but it can be helpful to add a few more steps to facilitate easy rollback.

Step 6: Update Deployment Tag Version

1. Add the step Update Deployment Tag Version.
2. Select the Environment
3. In the deployment section, set up two tags, the Existing Tag and the New Tag. The tag created earlier in the tutorial is named current. This will be the existing tag.
4. For the New Tag field enter the string previous.

Tagging the existing deployment keeps the previous version available for rollback. This also enables later use of the prune function to clean up untagged deployments.

Step 7: Update Deployment Tag Version

1. Add an additional Update Deployment Tag Version step.
2. Select the Environment
3. Set Deployment Type to Version
4. For Existing Version target the {{deployment-version}} pipeline variable used in earlier steps
5. In the New Tag field, set the tag to current

There are now two deployments: one tagged previous for the earlier deployment and one tagged current for the latest deployment. This setup allows for easy rollback by simply updating the tag.

Step 8: Prune Environment Deployments

The final step is Prune Environment Deployments. This step will take the environment and remove all deployments in that environment that do not have a tag.

1. Add the step Prune Environment Deployments
2. Select the Environment

Next Steps

Trigger Pipeline

Once the pipeline is created, it can be run it using the Trigger Pipeline button at the top of the screen. Since a pipeline variable is used, click the V button next to Trigger Pipeline to open the variable entry modal. A prompt will appear to enter a variable that will replace all instances of {{deployment-version}} in the pipeline.

Use Trigger Keys

A more advanced option for running the pipeline is using a trigger key. Generate a trigger key to run the pipeline remotely from a local machine or integrate it into a CI/CD pipeline.