DEV Community: Angel Rivera

What developers get, out-of-the-box, from the most generous free plan anywhere

Angel Rivera — Tue, 11 Jan 2022 13:00:00 +0000

Freemium plans are a great way for companies to introduce developers to their products and offer a hands-on demonstration of the value they provide. But it can be extremely frustrating for developers when a free tier limits access to key features or doesn’t provide enough capacity to evaluate how the product performs in real-world development scenarios. Not only is this frustrating, but it also diminishes the overall developer experience, resulting in negative and sometimes inaccurate perceptions of the product.

Many companies struggle to strike the right balance between which features to include in their free tier and at what level of usage they should require a paid account. CircleCI is no exception. Until recently, our free plan just wasn’t enough to provide the best developer experience and demonstrate the value and power that CircleCI can bring to your continuous delivery and release processes. That’s why we decided to overhaul our offerings to provide the most comprehensive free plan available on the market.

In this post, I’ll discuss the newly released CircleCI Free plan, highlighting some of the most impactful changes and how they will improve the developer experience.

Free plan details

Developers continually adopt innovative strategies and concepts like continuous delivery and release management processes with the goal of building and releasing software faster and more efficiently. CircleCI enables your team to maximize development velocity by automating their software build and release practices. With our new free tier offerings, you get access to all the features and capabilities you need to make the most of your build minutes. Here’s what you get with the new free plan:

Unlimited users
30,000 credits per month—enough for up to 6,000 build minutes, depending on your compute type
Access to multiple execution environments, including Docker, Linux, Arm, and Windows, and larger resource classes
30 concurrent job runs on any of the available compute options
5 self-hosted runners to run jobs on your own machines
1 GB of network data transfer to self-hosted runners and 2 GB of data storage for saving caches and workspaces, uploading test results, and building artifacts
Docker layer caching to speed up your Docker builds
Flaky test detection on our Insights dashboard for up to 5 tests
The ability to create private orbs for sharing configuration code with other members of your team

Now that I’ve briefly described the awesome products and features included in the new Free plan, let’s take a closer look at some of the features that matter most to developers and their teams.

Larger resource classes

Release cycles are growing increasingly shorter so that teams can ship changes and new features to users as quickly as possible. For developers to meet their release cycle requirements, it’s critical that they execute highly efficient CI/CD pipelines on the changes to be released. There are many ways to optimize your CI/CD pipelines, and one of the easiest and most effective is to control the pipeline’s underlying compute node capacity via a feature known as the resource class.

The resource class feature enables teams to configure and manage the capacity of compute node resources such as CPU and RAM, ensuring that the pipeline has the appropriate horsepower to successfully and expediently complete pipeline jobs. More often than not, pipeline job resource classes are configured with insufficient resource capacities, resulting in dramatically slower runs. These slower runs incrementally extend the duration of pipeline completions, which can lead to delays in the release process. The new Free plan provides access to a wider range of resources classes, enabling teams to dial in the right resources to optimize their pipeline job performance.

30x concurrency

Beyond providing appropriate compute capacities for pipeline jobs, another feature teams can use to speed up their pipelines is concurrency, which is the ability to run multiple jobs at the same time across multiple execution environments. Under the new Free plan, you can now run up to 30 jobs concurrently, which can yield significant time savings by allowing you to avoid queuing caused by resource constraints in a given execution environment.

A great use case for concurrency within pipelines is parallel test execution. The more tests your project has, the longer it will take for them to complete on a single machine. To reduce this time, you can run tests in parallel by specifying a parallelism level in your job configuration. Your tests will then run simultaneously across multiple separate executors, allowing you to shorten the amount of time it takes to validate and ship changes to your users. For more information on parallelism and concurrency, review the documentation.

Docker layer caching

Docker is the containerization technology available within the CircleCI platform. Docker images allow teams to spin up container environments to run jobs, and many teams build their own Docker images to have custom environments to test and deploy their applications. Docker images are built from Dockerfiles, and each command in the Dockerfile produces a layer in the image. Building Docker images can be one of the most time-consuming tasks in a CI/CD workflow.

With Docker layer caching, now available on the CircleCI Free plan, you can reduce the time spent on repeated Docker builds by saving individual layers of your Docker image on every job run. The next time you run your workflow, CircleCI will retrieve any unchanged layers from the cache rather than rebuilding the entire image from scratch. This enables teams to efficiently package their apps and build related Docker images without slowing down pipeline executions. For more information about Docker layer caching, check out the documentation.

Private orbs

Orbs are reusable packages of YAML that make it easier for developers to automate processes and incorporate third-party tools in their pipelines as well as share configuration across projects. While there are many useful orbs available in our public orbs registry, teams working in higly regulated industries such as healthcare, finance, or the public sector often require higher levels of security and compliance.

With private orbs, your team gets all of the collaboration and efficiency advantages of orbs along with the increased privacy and security that comes from restricting access to authenticated users within your organization. Your team can create and publish new private orbs using the CLI tool, and authenticated users can view and manage your organization’s private orbs by visiting the Orbs page in the Organization Settings tab of the CircleCI web app.

Test Insights with flaky test detection

Automatically testing changes to your code is the foundation of continuous integration and is an essential step toward minimizing risk in your software releases. But the reality is that most tests aren’t perfect. They don’t always execute as expected and can sometimes be flaky, meaning they fail nondeterministically. With the CircleCI Insights dashboard, you can monitor test performance across multiple workflows and development branches to automatically identify tests that are slow, flaky, or fail most often.

Insights gives developers valuable visibility into test execution and performance data. Improved awareness of the health and performance of your test suite can save your team time and money by eliminating hours spent chasing unidentified bugs and increasing your confidence in the quality of your code. Plus, with Insights, you can monitor other key metrics, including credit usage, success rates, and pipeline duration, so that you can get a complete overview of your workflow performance at a glance. To learn more, visit the Insights documentation.

Conclusion

In this post, I discussed the newly released CircleCI free plan and highlighted some of the changes that will provide the biggest improvements to the developer experience. With access to the complete feature set on CircleCI’s powerful continuous integration and delivery platform, your team can implement fast, flexible, and efficient CI/CD pipelines that will drastically shorten the time from commit to deploy.

Automating development processes with continuous delivery is no longer optional for software producers who want to be responsive to their users’ needs and stay ahead of the competition. To learn more about CircleCI’s pricing and how it compares to other plans available on the market, visit our pricing page. If your team isn’t already benefitting from the time savings and confidence boost that a robust CI/CD solution can provide, sign up for a free CircleCI account and get started today.

Infrastructure as Code, part 3: automate Kubernetes deployments with CI/CD and Terraform

Angel Rivera — Thu, 11 Nov 2021 17:00:00 +0000

This series shows you how to get started with infrastructure as code (IaC). The goal is to help developers build a strong understanding of IaC through tutorials and code examples.

In this post, I will demonstrate how to create continuous integration and deployment (CI/CD) pipelines that automate the Terraform IaC deployments covered in part 1 and part 2 of this series. Here is a quick list of things we will accomplish in this post:

Build a new CircleCI .config.yml file for the project
Configure new jobs and workflows
Automate the execution of Terraform code to create Google Kubernetes Engine (GKE) clusters and deploy the application

Note: Before you can go through this part of the tutorial, make sure you have completed all the actions in the prerequisites section of part 1.

We will start with a quick explanation of what CI/CD is, and a review of the previous two installments of this tutorial series. Then you can start learning about the CircleCI .config.yml file included in this code repo.

Continuous integration and continuous deployment

CI/CD pipelines help developers and teams automate their build and test processes. CI/CD creates valuable feedback loops that provide a near-realtime status of software development processes. The CI/CD automation also provides consistent process execution and accurate results. This helps in optimizing these processes and contributes to velocity gains. Streamlining development practices with CI/CD is becoming common practice among teams. Understanding how to integrate and automate repeated tasks is critical in building valuable CI/CD pipelines.

In part 1 and part 2, we used Terraform to create a new GKE cluster and related Kubernetes objects that deploy, execute, and serve an application. These Terraform commands were executed manually from our terminal. That works well when you are developing the Terraform code or modifying it, but we want to automate the execution of those commands. There are many ways to automate them, but we are going to focus on how to do it from within CI/CD pipelines.

What are CircleCI pipelines?

CircleCI pipelines are the full set of processes you run when you trigger work on your projects. Pipelines encompass your workflows, which in turn coordinate your jobs. This is all defined in your project configuration file. In the next sections of this tutorial, we will define a CI/CD pipeline to build our project.

Setting up the project on CircleCI

Before we start building a config.yml file for this project, we need to add the project to CircleCI. If you are unfamiliar with the process, you can use the setting up CircleCI guide here. Once you have completed the Setting up CircleCI section, stop there so we can configure project level environment variables.

Project level environment variables

Some jobs in this pipeline will need access to authentication credentials to execute commands on the target service. In this section, we will define the required credentials for some of our jobs and demonstrate how to input them into CircleCI as project level environment variables. For each variable, input the EnVar Name: value in the Name field and input the credentials in the Value field. Here is a list of credentials that our pipeline will need, and their values:

EnVar Name: TF_CLOUD_TOKEN - Value: The Base64 encoded value of the local .terraformrc file which hosts the Terraform Cloud user token
EnVar Name: DOCKER_LOGIN - Value: Docker Hub username
EnVar Name: DOCKER_PWD - Value: Docker Hub password
EnVar Name: GOOGLE_CLOUD_KEYS - Value: The Base64 encoded value of the GCP credential JSON file

Once all of the environment variables above are in place, we can begin building our pipeline in the config.yml file.

The CircleCI config.yml

The config.yml file is where you define CI/CD related jobs to be processed and executed. In this section, we will define the jobs and workflows for our pipeline.

Open the .circleci/.config.yml file in an editor, delete its contents and paste this code:

version: 2.1
jobs:

The version: key specifies the platform features to use when running this pipeline. The jobs: key represents the list of individual jobs that we will define for this pipeline. Next, we will create the jobs that our pipeline will execute.

Job - run_tests:

I encourage you to familiarize yourself with the special keys, capabilities, and features in this CircleCI reference doc which should help you gain experience with the platform. Here is a general outline and explanation for each of the keys in the job we are about to discuss.

docker: is a key represents the runtime our job will be executing in
- image: is a key represents the Docker container to use for this job
steps: is a key represents a list or collection of executable commands which are run during a job
- checkout: is a key is a special step used to check out source code to the configured path
- run: is a key is used to invoke all command-line programs
- name: is a key represents the title of the step to be shown in the CircleCI UI
- command: is a key represents the command to run via the shell
- store_test_results: is a key represents a special step used to upload and store test results for a build
- path: is the path (absolute, or relative to your working_directory) to the directory containing subdirectories of JUnit XML or Cucumber JSON test metadata files
- store_artifacts: is a key that represents a step to store artifacts (for example logs, binaries, etc) for availability in the web app or through the API
- path: is the path to the directory in the primary container used for saving job artifacts

A valuable benefit of CI/CD is the ability to execute automated testing on newly written code. It helps identify known and unknown bugs in code by executing tests on code every time it is modified.

Our next step is to define a new job in the config.yml file. Paste the following into the file:

  run_tests:
    docker:
      - image: circleci/node:12
    steps:
      - checkout
      - run:
          name: Install npm dependencies
          command: |
            npm install --save
      - run:
          name: Run Unit Tests
          command: |
            ./node_modules/mocha/bin/mocha test/ --reporter mochawesome --reporter-options reportDir=test-results,reportFilename=test-results
      - store_test_results:
          path: test-results

Here is a breakdown of what we just added.

The docker: and image: keys specify the executor and the Docker image we are using in this job
The command: npm install --save key installs the application dependencies used in the app
name: Run Unit Tests executes the automated tests and saves them to a local directory called test-results/
store_test_results: is a special command that saves and pins the test-results/ directory results to the build in CircleCI

This job serves as a unit testing function. It helps with identifying errors in the code. If any of these tests fail, the entire pipeline build will fail, and prompt the developers to fix the errors. The goal is for all the tests and jobs to pass. Next, we will create a job that will build a Docker image and push it to the Docker Hub registry.

Job - build_docker_image

In part 2 of this series, we manually created a Docker image and pushed it to the Docker Hub registry. In this job, we will use automation to complete this task instead. Append this code block to the config.yml file:

  build_docker_image:
    docker:
      - image: circleci/node:12
    steps:
      - checkout
      - setup_remote_docker:
          docker_layer_caching: false
      - run:
          name: Build Docker image
          command: |
            export TAG=0.2.<< pipeline.number >>
            export IMAGE_NAME=$CIRCLE_PROJECT_REPONAME            
            docker build -t $DOCKER_LOGIN/$IMAGE_NAME -t $DOCKER_LOGIN/$IMAGE_NAME:$TAG .
            echo $DOCKER_PWD | docker login -u $DOCKER_LOGIN --password-stdin
            docker push $DOCKER_LOGIN/$IMAGE_NAME

The build_docker_image job is pretty straightforward. You have already encountered most of the CircleCI YAML keys it uses, so I will just jump into the name: Build Docker Image command block.

The export TAG=0.2.<< pipeline.number >> line defines a local environment variable that uses the pipeline.number value to associate the Docker tag value to the pipeline number being executed
The export IMAGE_NAME=$CIRCLE_PROJECT_REPONAME defines the variable we’ll use in naming the Docker image
docker build -t $DOCKER_LOGIN/$IMAGE_NAME -t $DOCKER_LOGIN/$IMAGE_NAME:$TAG . executes the Docker build command using a combination of the project level variables that we set earlier and the local environment variables we specified
echo $DOCKER_PWD | docker login -u $DOCKER_LOGIN --password-stdin authenticates our Docker Hub credentials to access the platform
The docker push $DOCKER_LOGIN/$IMAGE_NAME uploads the new docker image to the Docker Hub registry

This should all look and feel familiar because these are the very same commands you ran manually in part 2. In this example, we added the environment variable naming bits. Next we will build a job to execute Terraform code that builds a GKE cluster.

Job - gke_create_cluster

In this job, we will automate the execution of the Terraform code found in the part03/iac_gke_cluster/ directory. Append this code block to the config.yml file, then save it:

  gke_create_cluster:
    docker:
      - image: ariv3ra/terraform-gcp:latest
    environment:
      CLOUDSDK_CORE_PROJECT: cicd-workshops
    steps:
      - checkout
      - run:
          name: Create GKE Cluster
          command: |
            echo $TF_CLOUD_TOKEN | base64 -d > $HOME/.terraformrc
            echo $GOOGLE_CLOUD_KEYS | base64 -d > $HOME/gcloud_keys
            gcloud auth activate-service-account --key-file ${HOME}/gcloud_keys
            cd part03/iac_gke_cluster/
            terraform init
            terraform plan -var credentials=$HOME/gcloud_keys -out=plan.txt
            terraform apply plan.txt

One thing to take note of in this code block is the executor Docker image image: ariv3ra/terraform-gcp:latest. This is an image that I built that has both the Google SDK and Terraform CLI installed. If we were not using this, we would need to add installation steps to this job to install and configure the tools every time. The environment: CLOUDSDK_CORE_PROJECT: cicd-workshops keys are also an important element. This sets the environment variable value needed for the gcloud cli commands we will be executing later.

Other elements used in the code block:

echo $TF_CLOUD_TOKEN | base64 -d > $HOME/.terraformrc is a command that decodes the $TF_CLOUD_TOKEN value, which creates the ./terraformrc file required by Terraform to access the state data on the respective Terraform cloud workspace
echo $GOOGLE_CLOUD_KEYS | base64 -d > $HOME/gcloud_keys is a command that decodes the $GOOGLE_CLOUD_KEYS value, which created the gcloud_keys file required by glcoud cli to access GCP
gcloud auth activate-service-account --key-file ${HOME}/gcloud_keys is a command that authorizes access to GCP using the gcloud_keys file we decoded and generated earlier

The rest of the commands are the terraform cli commands with -var parameters that specify and override the default values of variables defined in the respective Terraform variables.tf file. Once the terraform apply plan.txt executes, this job will create a new GKE Cluster.

Job - gke_deploy_app

In this job, we will automate the execution of the Terraform code found in the part03/iac_kubernetes_app/ directory. Append this code block to the config.yml file, then save it:

  gke_deploy_app:
    docker:
      - image: ariv3ra/terraform-gcp:latest
    environment:
      CLOUDSDK_CORE_PROJECT: cicd-workshops
    steps:
      - checkout
      - run:
          name: Deploy App to GKE
          command: |
            export CLUSTER_NAME="cicd-workshops"
            export TAG=0.2.<< pipeline.number >>
            export DOCKER_IMAGE="docker-image=${DOCKER_LOGIN}/${CIRCLE_PROJECT_REPONAME}:$TAG"
            echo $TF_CLOUD_TOKEN | base64 -d > $HOME/.terraformrc
            echo $GOOGLE_CLOUD_KEYS | base64 -d > $HOME/gcloud_keys
            gcloud auth activate-service-account --key-file ${HOME}/gcloud_keys
            gcloud container clusters get-credentials $CLUSTER_NAME --zone="us-east1-d"
            cd part03/iac_kubernetes_app
            terraform init
            terraform plan -var $DOCKER_IMAGE -out=plan.txt
            terraform apply plan.txt
            export ENDPOINT="$(terraform output endpoint)"
            mkdir -p /tmp/gke/ && echo 'export ENDPOINT='${ENDPOINT} > /tmp/gke/gke-endpoint
      - persist_to_workspace:
          root: /tmp/gke
          paths:
            - "*"

Here are the important elements of this job code block and some new elements we haven’t previously discussed.

export CLUSTER_NAME="cicd-workshops" defines a variable that holds the name of the GCP project that we’ll be deploying to.
gcloud container clusters get-credentials $CLUSTER_NAME --zone="us-east1-d" is a command that retrieves the kubeconfig data from the GKE cluster we created in the previous job.
terraform plan -var $DOCKER_IMAGE -out=plan.txt is a command that overrides the default values of respective variables defined in the respective Terraform variables.tf file.
export ENDPOINT="$(terraform output endpoint)" assigns the output endpoint value generated by the Terraform command to a local environment variable which will be saved to a file and persisted to a CircleCI workspace. It can then be retrieved, attached from an attached CircleCI workspace and used in follow up jobs.

Job - gke_destroy_cluster

This job is the last one we will build for this pipeline. It will basically destroy all of the resources and infrastructure that we have built in previous CI/CD jobs. As part of testing, ephemeral resources are used for smoke testing, integration testing, performance testing, and other types. A job that executes destroy commands is great for getting rid of these constructs when they are no longer required.

In this job we will automate the execution of the Terraform code found in the part03/iac_kubernetes_app/ directory. Append this code block to the config.yml file, then save it:

  gke_destroy_cluster:
    docker:
      - image: ariv3ra/terraform-gcp:latest
    environment:
      CLOUDSDK_CORE_PROJECT: cicd-workshops
    steps:
      - checkout
      - run:
          name: Destroy GKE Cluster
          command: |
            export CLUSTER_NAME="cicd-workshops"
            export TAG=0.2.<< pipeline.number >>
            export DOCKER_IMAGE="docker-image=${DOCKER_LOGIN}/${CIRCLE_PROJECT_REPONAME}:$TAG"            
            echo $TF_CLOUD_TOKEN | base64 -d > $HOME/.terraformrc
            echo $GOOGLE_CLOUD_KEYS | base64 -d > $HOME/gcloud_keys
            gcloud auth activate-service-account --key-file ${HOME}/gcloud_keys
            cd part03/iac_kubernetes_app
            terraform init
            gcloud container clusters get-credentials $CLUSTER_NAME --zone="us-east1-d"            
            terraform destroy -var $DOCKER_IMAGE --auto-approve
            cd ../iac_gke_cluster/
            terraform init
            terraform destroy -var credentials=$HOME/gcloud_keys --auto-approve

The important element of this job code block is the terraform destroy -var credentials=$HOME/gcloud_keys --auto-approve command. This command that executes the Terraform command that destroys all of the resources created with the Terraform code in the part03/iac_gke_cluster and part03/iac_kubernetes_app/ directories respectively.

Now that we have defined all of the jobs in our pipeline we are ready to create CircleCI workflows that will orchestrate how the jobs will be executed and processed within the pipeline.

Creating CircleCI workflows

Our next step is to create the workflows that define how jobs will be executed and processed. Think of a workflow as an ordered list for jobs. You can specify when and how to execute these jobs using the workflow. Append this workflow code block to the config.yml file:

workflows:
  build_test:
    jobs:
      - run_tests
      - build_docker_image
      - gke_create_cluster
      - gke_deploy_app:
          requires:
            - run_tests
            - build_docker_image
            - gke_create_cluster
      - approve-destroy:
          type: approval
          requires:
            - gke_create_cluster
            - gke_deploy_app
      - gke_destroy_cluster:
          requires:
            - approve-destroy

This code block represents the workflows definition of our pipeline. Here is what is going on in this block:

The workflows: key specifies a workflow element
build_test: represents the name/identifier of this workflow
The jobs: key represents the list of jobs defined in the config.yml file to execute

In this list, you specify the jobs you want to execute in this pipeline. Here is our list of jobs:

      - run_tests
      - build_docker_image
      - gke_create_cluster
      - gke_deploy_app:
          requires:
            - run_tests
            - build_docker_image
            - gke_create_cluster
      - approve-destroy:
          type: approval
          requires:
            - gke_create_cluster
            - gke_deploy_app
      - gke_destroy_cluster:
          requires:
            - approve-destroy

The run_tests, build_docker_image, and gke_create_cluster workflow jobs run in parallel or concurrently, unlike the gke_deploy_app: item that has a requires: key. Jobs are run in parallel by default, so you must explicitly require any dependencies by their job name using a requires: key and a list of jobs that must be complete before kicking off the job specified. Think of requires: keys as building dependencies on the success of other jobs. These keys let you segment and control the execution of your pipeline.

The approve-destroy: item specifies a job with a manual approval step. It requires human intervention where someone must approve the execution of the next job in the workflow jobs list. The next job, gke_destroy_cluster:, is dependent on the approval-destroy: job being completed before it executes. It destroys all the resources created by previously executed jobs in the pipeline.

The complete .config.yml file

A complete config.yml based for this post and can be found in the project code repo in the .circleci/ directory. It is here for you to review:

version: 2.1
jobs:
  run_tests:
    docker:
      - image: circleci/node:12
    steps:
      - checkout
      - run:
          name: Install npm dependencies
          command: |
            npm install --save
      - run:
          name: Run Unit Tests
          command: |
            ./node_modules/mocha/bin/mocha test/ --reporter mochawesome --reporter-options reportDir=test-results,reportFilename=test-results
      - store_test_results:
          path: test-results
      - store_artifacts:
          path: test-results
  build_docker_image:
    docker:
      - image: circleci/node:12
    steps:
      - checkout
      - setup_remote_docker:
          docker_layer_caching: false
      - run:
          name: Build Docker image
          command: |
            export TAG=0.2.<< pipeline.number >>
            export IMAGE_NAME=$CIRCLE_PROJECT_REPONAME
            docker build -t $DOCKER_LOGIN/$IMAGE_NAME -t $DOCKER_LOGIN/$IMAGE_NAME:$TAG .
            echo $DOCKER_PWD | docker login -u $DOCKER_LOGIN --password-stdin
            docker push $DOCKER_LOGIN/$IMAGE_NAME
  gke_create_cluster:
    docker:
      - image: ariv3ra/terraform-gcp:latest
    environment:
      CLOUDSDK_CORE_PROJECT: cicd-workshops
    steps:
      - checkout
      - run:
          name: Create GKE Cluster
          command: |
            echo $TF_CLOUD_TOKEN | base64 -d > $HOME/.terraformrc
            echo $GOOGLE_CLOUD_KEYS | base64 -d > $HOME/gcloud_keys
            gcloud auth activate-service-account --key-file ${HOME}/gcloud_keys
            cd part03/iac_gke_cluster/
            terraform init
            terraform plan -var credentials=$HOME/gcloud_keys -out=plan.txt
            terraform apply plan.txt
  gke_deploy_app:
    docker:
      - image: ariv3ra/terraform-gcp:latest
    environment:
      CLOUDSDK_CORE_PROJECT: cicd-workshops
    steps:
      - checkout
      - run:
          name: Deploy App to GKE
          command: |
            export CLUSTER_NAME="cicd-workshops"
            export TAG=0.2.<< pipeline.number >>
            export DOCKER_IMAGE="docker-image=${DOCKER_LOGIN}/${CIRCLE_PROJECT_REPONAME}:$TAG"
            echo $TF_CLOUD_TOKEN | base64 -d > $HOME/.terraformrc
            echo $GOOGLE_CLOUD_KEYS | base64 -d > $HOME/gcloud_keys
            gcloud auth activate-service-account --key-file ${HOME}/gcloud_keys
            gcloud container clusters get-credentials $CLUSTER_NAME --zone="us-east1-d"
            cd part03/iac_kubernetes_app
            terraform init
            terraform plan -var $DOCKER_IMAGE -out=plan.txt
            terraform apply plan.txt
            export ENDPOINT="$(terraform output endpoint)"
            mkdir -p /tmp/gke/
            echo 'export ENDPOINT='${ENDPOINT} > /tmp/gke/gke-endpoint
      - persist_to_workspace:
          root: /tmp/gke
          paths:
            - "*"
  gke_destroy_cluster:
    docker:
      - image: ariv3ra/terraform-gcp:latest
    environment:
      CLOUDSDK_CORE_PROJECT: cicd-workshops
    steps:
      - checkout
      - run:
          name: Destroy GKE Cluster
          command: |
            export CLUSTER_NAME="cicd-workshops"
            export TAG=0.2.<< pipeline.number >>
            export DOCKER_IMAGE="docker-image=${DOCKER_LOGIN}/${CIRCLE_PROJECT_REPONAME}:$TAG"            
            echo $TF_CLOUD_TOKEN | base64 -d > $HOME/.terraformrc
            echo $GOOGLE_CLOUD_KEYS | base64 -d > $HOME/gcloud_keys
            gcloud auth activate-service-account --key-file ${HOME}/gcloud_keys
            cd part03/iac_kubernetes_app
            terraform init
            gcloud container clusters get-credentials $CLUSTER_NAME --zone="us-east1-d"            
            terraform destroy -var $DOCKER_IMAGE --auto-approve
            cd ../iac_gke_cluster/
            terraform init
            terraform destroy -var credentials=$HOME/gcloud_keys --auto-approve
workflows:
  build_test:
    jobs:
      - run_tests
      - build_docker_image
      - gke_create_cluster
      - gke_deploy_app:
          requires:
            - run_tests
            - build_docker_image
            - gke_create_cluster
      - approve-destroy:
          type: approval
          requires:
            - gke_create_cluster
            - gke_deploy_app
      - gke_destroy_cluster:
          requires:
            - approve-destroy

Conclusion

Congratulations! You have just completed part 3 of this series and leveled up your experience by building a new config.yml file that executes IaC resources using Terraform. This post explained and demonstrated some critical elements in the config.yml file and the internal concepts related to the CircleCI platform.

In this series we covered many concepts and technologies such as Docker, GCP, Kubernetes, Terraform and CircleCI and included some hands-on experience with them. We also covered how to wire up your projects to use CircleCI and leverage the Terraform code to test your application in target deployment environments. This series is intended to increase your knowledge of important DevOps concepts, technologies, and how they all work together.

I encourage you to experiment on your own and with your team; changing code, adding new Terraform providers, and reconfiguring CI/CD jobs and pipelines. Challenge each other to accomplish release goals using a combination of what you learned and other ideas the team comes up with. By experimenting, you will learn more than any blog post could teach you.

Thank you for following along with this series. I hope you found it useful. Please feel free to reach out with feedback on Twitter @punkdata.

The following resources will help you expand your knowledge:

Infrastructure as Code, part 2: build Docker images and deploy to Kubernetes with Terraform

Angel Rivera — Tue, 09 Nov 2021 20:00:00 +0000

This series shows you how to get started with infrastructure as code (IaC). The goal is to help developers build a strong understanding of IaC through tutorials and code examples.

In this post, I will demonstrate how to how to create a Docker image for an application, then push that image to Docker Hub. I will also discuss how to create and deploy the Docker image to a Google Kubernetes Engine (GKE) cluster using HashiCorp’s Terraform.

Here is a quick list of things we will accomplish in this post:

Build a new Docker image
Push the new Docker image to the Docker Hub registry
Create a new GKE cluster using Terraform
Create a new Terraform Kubernetes Deployment using the Terraform Kubernetes provider
Destroy all the resources created using Terraform

Note: Before you can go through this part of the tutorial, make sure you have completed all the actions in the prerequisites section of part 1.

Our first task is learning how to build a Docker image based on the example Node.js application included in this code repo.

Building a Docker image

In the previous post, we used Terraform to create a new GKE cluster, but that cluster was unusable because no application or service was deployed. Because Kubernetes (K8s) is a container orchestrator, apps and services must be packaged into Docker images, which can then spawn Docker containers that execute applications or services.

Docker images are created using the docker build command and you will need a Dockerfile to specify how to build your Docker images. I will discuss Dockerfiles, but first I want to address .dockerignore files.

What is the .dockerignore file?

The .dockerignore file excludes the files and directories that match the patterns declared in it. Using this file helps to avoid unnecessarily sending large or sensitive files and directories to the daemon, and potentially adding them to public images. In this project, the .dockerignore file excludes unnecessary files related to Terraform and Node.js local dependencies.

Understanding the Dockerfile

The Dockerfile is critical for building Docker images. It specifies how to build and configure the image, in addition to what files to import into it. Dockerfile files are dynamic, so you can accomplish many objectives in different ways. It is important that you have a solid understanding of Dockerfile capabilities so you can build functional images. Here is a breakdown the Dockerfile contained in this project’s code repo.

FROM node:12

# Create app directory
WORKDIR /usr/src/app

# Install app dependencies
COPY package*.json ./

RUN npm install --only=production

# Bundle app source
COPY . .

EXPOSE 5000
CMD ["npm", "start"]

The FROM node:12 line defines an image to inherit from. When building images, Docker inherits from a parent image. In this case it is the node:12 image, which is pulled from Docker Hub, if it does not exist locally.

# Create app directory
WORKDIR /usr/src/app

# Install app dependencies
COPY package*.json ./

RUN npm install --only=production

This code block defines the WORKDIR parameter, which specifies the working directory in the Docker image. The COPY package*.json ./ line copies over any package-related files to the Docker image. The RUN npm install line installs the application dependencies listed in the package.json file.

COPY . .

EXPOSE 5000
CMD ["npm", "start"]

This code block copies all the files into the Docker image, except for the files and directories listed in the .dockerignore file. The EXPOSE 5000 line specifies the port to expose for this Docker image. The CMD ["npm", "start"] line defines how to start this image. In this case, it is executing the start section specified in the package.json file for this project. This CMD parameter is the default execution command. Now that you understand the Dockerfile, you can use it to build an image locally.

Using the Docker build command

Using the docker build command, the Dockerfile build a new imaged based on the directives defined in it. There are some naming conventions to keep in mind when you are building Docker images. Naming conventions are especially important if you plan on sharing the images.

Before we start building an image, I will take a moment to describe how to name them. Docker images use tags composed of slash-separated name components. Because we will be pushing the image to Docker Hub, we need to prefix the image name with our Docker Hub username. In my case, that is ariv3ra/. I usually follow that with the name of the project, or a useful description of the image. The full name of this Docker image will be ariv3ra/learniac:0.0.1. The :0.0.1 is a version tag for the application, but you could also use that to describe other details about the image.

Once you have a good, descriptive name, you can build an image. The following command must be executed from within the root of the project repo (be sure to replace ariv3ra with your Docker Hub name):

docker build -t ariv3ra/learniac -t ariv3ra/learniac:0.0.1 .

Next, run this command to see a list a of Docker images on your machine:

docker images

This was my output.

REPOSITORY TAG IMAGE ID CREATED SIZE
ariv3ra/learniac 0.0.1 ba7a22c461ee 24 seconds ago 994MB
ariv3ra/learniac latest ba7a22c461ee 24 seconds ago 994MB

The Docker push command

Now we are ready to push this image to Docker Hub and make it available publicly. Docker Hub requires authorization to access the service, so we need to use the login command to authenticate. Run this command to log in:

docker login

Enter your Docker Hub credentials in the prompts to authorize your account. You will need to log in only once per machine. Now you can push the image.

Using the image name listed in your docker images command, run this command:

docker push ariv3ra/learniac

This was my output.

The push refers to repository [docker.io/ariv3ra/learniac]
2109cf96cc5e: Pushed 
94ce89a4d236: Pushed 
e16b71ca42ab: Pushed 
8271ac5bc1ac: Pushed 
a0dec5cb284e: Mounted from library/node 
03d91b28d371: Mounted from library/node 
4d8e964e233a: Mounted from library/node

You now have a Docker image available in Docker Hub and ready to be deployed to a GKE cluster. All the pieces are in place to deploy your application to a new Kubernetes cluster. The next step is to build the Kubernetes Deployment using Terraform.

Using Terraform to deploy Kubernetes

In part 1 of this series, we learned how to create a new Google Kubernetes Engine (GKE) cluster using Terraform. As I mentioned earlier, that cluster was not serving any applications or services because we did not deploy any to it. In this section I will describe what it takes to deploy a Kubernetes Deployment using Terraform.

Terraform has a Kubernetes Deployment resource that lets you define a and execute a Kubernetes deployment to your GKE cluster. In part 1 we created a new GKE cluster using the Terraform code in the part01/iac_gke_cluster/ directory. In this post, we will use the part02/iac_gke_cluster/ and part02/iac_kubernetes_app/ directories, respectively. The iac_gke_cluster/ is the same code we used in part 1. We will be using it again here in conjunction with the iac_kubernetes_app/ directory.

Terraform Kubernetes provider

We previously used the Terraform Google Cloud Platform provider to create a new GKE cluster. The Terraform provider is specific to the Google Cloud Platform, but it is still Kubernetes under the hood. Because GKE is essentially a Kubernetes cluster, we need to use the Terraform Kubernetes provider and Kubernetes Deployment resource to configure and deploy our application to the GKE cluster.

Terraform code files

The part02/iac_kubernetes_app/ directory contains these files:

providers.tf
variables.tf
main.tf
deployments.tf
services.tf
output.tf

These files maintain all the code that we are using to define, create, and configure our application deployment to a Kubernetes cluster. Next, I will break down these files to give you a better understanding of what they do.

Breakdown: providers.tf

The provider.tf file is where we define the Terraform provider we will be using: the Terraform Kubernetes provider. The provider.tf:

provider "kubernetes" {

}

This code block defines the providers that will be used in this Terraform project. The { } blocks are empty because we will be handling the authentication requirements with a different process.

Breakdown: variables.tf

This file should seem familiar and is similar to the part 1 variables.tf file. This particular file specifies only the input variables that this Terraform Kubernetes project uses.

variable "cluster" {
  default = "cicd-workshops"
}
variable "app" {
  type = string
  description = "Name of application"
  default = "cicd-101"
}
variable "zone" {
  default = "us-east1-d"
}
variable "docker-image" {
  type = string
  description = "name of the docker image to deploy"
  default = "ariv3ra/learniac:latest"
}

The variables defined in this file will be used throughout the Terraform project in code blocks in the project files. All of these variables have default values that can be changed by defining them in the CLI when executing the code. These variables add much needed flexibility to the Terraform code and allows the reuse of valuable code. One thing to note here is that the variable "docker-image" default parameter is set to my Docker image name. Replace that value with the name of your Docker image.

Breakdown: main.tf

The elements of the main.tf file start with the terraform block, which specifies the type of Terraform Backend. A “backend” in Terraform determines how state is loaded and how an operation such as apply is executed. This abstraction enables non-local file state storage and remote execution among other things. In this code block, we are using the remote backend. It uses the Terraform Cloud, and is connected to the iac_kubernetes_app workspace you created in the Prerequisites section of the part 1 post.

terraform {
  required_version = "~>0.12"
  backend "remote" {
    organization = "datapunks"
    workspaces {
      name = "iac_kubernetes_app"
    }
  }
}

Breakdown: deployments.tf

Next up is a description of the syntax in the deployments.tf file. This file uses the Terraform Kubernetes Deployment resource to define, configure, and create all the Kubernetes resources required to release our application to the GKE cluster.

resource "kubernetes_deployment" "app" {
  metadata {
    name = var.app
    labels = {
      app = var.app
    }
  }
  spec {
    replicas = 3

    selector {
      match_labels = {
        app = var.app
      }
    }
    template {
      metadata {
        labels = {
          app = var.app
        }
      }
      spec {
        container {
          image = var.docker-image
          name = var.app
          port {
            name = "port-5000"
            container_port = 5000
          }
        }
      }
    }
  }
}

Time to review the code elements to gain a better understanding of what is going on.

resource "kubernetes_deployment" "app" {
  metadata {
    name = var.app
    labels = {
      app = var.app
    }
  }

This code block specifies the use of the Terraform Kubernetes Deployment resources, which defines our deployment object for Kubernetes. The metadata block is used to assign values for the parameters used within the Kubernetes services.

  spec {
    replicas = 3

    selector {
      match_labels = {
        app = var.app
      }
    }

    template {
      metadata {
        labels = {
          app = var.app
        }
      }

      spec {
        container {
          image = var.docker-image
          name = var.app
          port {
            name = "port-5000"
            container_port = 5000
          }
        }
      }
    }
  }

In the resources spec{...} block, we’re specifying that we want three Kubernetes pods running for our application in the cluster. The selector{...} block represents label selectors. These are a core grouping primitive in Kubernetes, which will let the users select a set of objects.

The resource template{...} block has a spec{...} block in it which has a container{...} properties block. This block has parameters that define and configure the container used in the deployment. As you can tell from the code, this is where we will define the pod’s Docker image (the image we want to use) and the container’s name as it should appear in Kubernetes. This is also where we define the port to expose on the container that will allow ingress access to the application running. The values come from the variables.tf file, found in the same folder. The Terraform Kubernetes Deployment resource is capable of performing very robust configurations. I encourage you and your team to experiment with some of the other properties to gain broader familiarity with the tooling.

Breakdown: services.tf

We have created a Terraform Kubernetes Deployment resource file and defined our Kubernetes deployment for this application. That leaves one detail left to complete the deployment of our app. The application we are deploying is a basic web site. As with all web sites, it needs to be accessible for it to be useful. At this point, our deployments.tf file specifies the directives for deploying a Kubernetes pod with our Docker image and the number of pods required. We are missing a critical element for our deployment: a Kubernetes service. This is an abstract way to expose an application running on a set of pods as a network service. With Kubernetes, you do not need to modify your application to use an unfamiliar service discovery mechanism. Kubernetes gives pods their own IP addresses and a single DNS name for a set of pods, and can load-balance across them.

The services.tf file is where we define a Terraform Kubernetes service. It will wire up the Kubernetes elements to provide ingress access to our application running on pods in the cluster. Here is the services.tf file.

resource "kubernetes_service" "app" {
  metadata {
    name = var.app
  }
  spec {
    selector = {
      app = kubernetes_deployment.app.metadata.0.labels.app
    }
    port {
      port = 80
      target_port = 5000
    }
    type = "LoadBalancer"
  }
}

At this point, it might be helpful to describe the spec{...} block and the elements within it. The selector{ app...} block specifies a name that was defined in the deployments.tf file and represents the app value in the label property of the metadata block in the deployments resource. This is an example of reusing values that have already been assigned in related resources. It also provides a mechanism that streamlines important values and establishes a form of referential integrity for important data like this.

The port{...} block has two properties: port and target_port. These parameters define the external port that the service will listen on for requests to the application. In this example, it is port 80. The target_port is the internal port our pods are listening on, which is port 5000. This service will route all traffic from port 80 to port 5000.

The last element to review here is the type parameter that specifies the type of service we are creating. Kubernetes has three types of services. In this example, we’re using the LoadBalancer type, which exposes the service externally using a cloud provider’s load-balancer. NodePort and ClusterIP Services, to which the external load balancer routes, are automatically created. In this case, GCP will create and configure a LoadBalancer that will control and route traffic to our GKE cluster.

Breakdown: output.tf

Terraform uses Output Values to return values of a Terraform module, which provides a child module with outputs after running terraform apply. These outputs are used to expose a subset of its resource attributes to a parent module, or to print certain values in the CLI output. The output.tf blocks we are using output values to readout values like Cluster name and the ingress IP address of our newly created LoadBalancer service. This address is where we can access our application hosted in Pods on the GKE cluster.

  output "gke_cluster" {
    value = var.cluster
  }

  output "endpoint" {
    value = kubernetes_service.app.load_balancer_ingress.0.ip
  }

Initializing the Terraform part02/iac_gke_cluster

Now that you have a better understanding of our Terraform project and syntax, you can start provisioning our GKE cluster using Terraform. Change directory into the part02/iac_gke_cluster directory:

cd part02/iac_gke_cluster

While in part02/iac_gke_cluster, run this command:

terrform init

This was my output.

Initializing the backend...

Successfully configured the backend "remote"! Terraform will automatically
use this backend unless the backend configuration changes.

Initializing provider plugins...
- Checking for available provider plugins...
- Downloading plugin for provider "google" (hashicorp/google) 3.31.0...

The following providers do not have any version constraints in configuration,
so the latest version was installed.

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.google: version = "~> 3.31"

Terraform has been successfully initialized!

This is great! Now we can create the GKE cluster.

Terraform apply part02/iac_gke_cluster

Terraform has a command that allows you to dry run and validate your Terraform code without actually executing anything. The command is called terraform plan and it also graphs all the actions and changes that Terraform will execute against your existing infrastructure. In the terminal, run:

terraform plan

This was my output.

Refreshing Terraform state in-memory prior to plan...
The refreshed state will be used to calculate this plan, but will not be
persisted to local or remote state storage.
-----------------------------------------------------------------------------
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # google_container_cluster.primary will be created
  + resource "google_container_cluster" "primary" {
      + additional_zones = (known after apply)
      + cluster_ipv4_cidr = (known after apply)
      + default_max_pods_per_node = (known after apply)
      + enable_binary_authorization = false
  ...

Terraform will create new GCP resources for you based on the code in the main.tf file. Now you are ready to create the new infrastructure and deploy the application. Run this command in the terminal:

terraform apply

Terraform will prompt you to confirm your command. Type yes and press Enter.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

Terraform will build your new Google Kubernetes Engine cluster on GCP.

Note : It will take 3-5 minutes for the cluster to complete. It is not an instant process because the backend systems are provisioning and bringing things online.

After my cluster was completed, this was my output.

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

cluster = cicd-workshops
cluster_ca_certificate = <sensitive>
host = <sensitive>
password = <sensitive>
username = <sensitive>

The new GKE cluster has been created and the Outputs results are displayed. Notice that the output values that were marked sensitive are masked in the results with <sensitive> tags. This ensures sensitive data is protected but available when needed.

Next, we will use the code in the part02/iac_kubernetes_app/ directory to create a Kubernetes deployment and accompanying LoadBalancer service.

Terraform Initialize part02/iac_kubernetes_app/

We can now deploy our application to this GKE cluster using the code in the part02/iac_kubernetes_app/ directory. Change directory into the directory with this command:

cd part02/iac_kubernetes_app/

While in part02/iac_kubernetes_app/, run this command to initialize the Terraform project:

terrform init

This was my output.

Initializing the backend...

Successfully configured the backend "remote"! Terraform will automatically
use this backend unless the backend configuration changes.

Initializing provider plugins...
- Checking for available provider plugins...
- Downloading plugin for provider "kubernetes" (hashicorp/kubernetes) 1.11.3...

The following providers do not have any version constraints in configuration,
so the latest version was installed.

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.kubernetes: version = "~> 1.11"

Terraform has been successfully initialized!

GKE cluster credentials

After creating a google_container_cluster with Terraform, authentication to the cluster is required. You can use the Google Cloud CLI to configure cluster access, and generate a kubeconfig file. Execute this command:

gcloud container clusters get-credentials cicd-workshops --zone="us-east1-d"

Using this command, gcloud will generate a kubeconfig entry that uses gcloud as an authentication mechanism. This command uses the cicd-workshops value as the cluster name which is also specified in the variables.tf.

Terraform apply part02/iac_kubernetes_app/

Finally, we are ready to deploy our application to the GKE cluster using Terraform. Execute this command:

terraform plan

This was my output.

Refreshing Terraform state in-memory prior to plan...
The refreshed state will be used to calculate this plan, but will not be
persisted to local or remote state storage.
-----------------------------------------------------------------------------
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create
Terraform will perform the following actions:
  # kubernetes_deployment.app will be created
  + resource "kubernetes_deployment" "app" {
      + id = (known after apply)
      + metadata {
          + generation = (known after apply)
          + labels = {
              + "app" = "cicd-101"
            }
          + name = "cicd-101"
          + namespace = "default"
          + resource_version = (known after apply)
          + self_link = (known after apply)
          + uid = (known after apply)
        }
  ...

Terraform will create new GCP resources for you based on the code in the deployment.tf and services.tf files. Now you can create the new infrastructure and deploy the application. Run this command in the terminal:

terraform apply

Terraform will prompt you to confirm your command. Type yes and press Enter.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

Terraform will build your new Kubernetes application deployment and related LoadBalancer.

Note : It will take 3-5 minutes for the cluster to complete. It is not an instant process because the backend systems are provisioning and bringing things online.

After my cluster was completed, this was my output.

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

endpoint = 104.196.222.238
gke_cluster = cicd-workshops

The application has now been deployed. The endpoint value, and the output, is the IP address to the public ingress of the cluster LoadBalancer. It also represents the address where you can access the application. Open a web browser and use the output value to access the application. There will be a web page with the text “Welcome to CI/CD 101 using CircleCI!”.

Using Terraform destroy

You have proof that your Kubernetes deployment works and that deploying the application to a GKE cluster has been successfully tested. You can leave it up and running, but be aware that there is a cost associated with any assets running on the Google Cloud Platform and you will be liable for those costs. Google gives a generous $300 credit for its free trial sign-up, but you could easily eat through that if you leave assets running.

Running the terraform destroy will terminate any running assets that you created in this tutorial.

Run this command to destroy the GKE cluster.

terraform destroy

Remember that the above command will only destroy the part02/iac_kubeernetes_app/ deployment and you need to run the following to destroy all the resources created in this tutorial.

cd ../iac_gke-cluster/

terraform destroy

This will destroy the GKE cluster we created earlier.

Conclusion

Congratulations! You have completed part 2 of this series, and leveled up your experience by building and publishing a new Docker image, along with provisioning and deploying an application to a Kubernetes cluster using infrastructure as code and Terraform.

Continue to part 3 of the tutorial where you will learn how to automate all of this awesome knowledge into CI/CD pipelines using CircleCI.

The following resources will help you expand your knowledge from here:

Infrastructure as Code, part 1: create a Kubernetes cluster with Terraform

Angel Rivera — Mon, 08 Nov 2021 16:00:00 +0000

This series shows you how to get started with infrastructure as code (IaC). The goal is to help developers build a strong understanding of IaC through tutorials and code examples.

Infrastructure as Code (IaC) is an integral part of modern continuous integration pipelines. It is the process of managing and provisioning cloud and IT resources using machine readable definition files. IaC gives organizations tools to create, manage, and destroy compute resources by statically defining and declaring these resources in code.

In this post, I will discuss how to use HashiCorp’s Terraform to provision, deploy, and destroy infrastructure resources. Before we start, you will need to create accounts in target cloud providers and services such as Google Cloud and Terraform Cloud. Then you can start learning how to use Terraform to create a new Google Kubernetes Engine (GKE) cluster

Prerequisites

Before you get started, you will need to have these things in place:

A Google Cloud Platform (GCP) account
- Google Cloud project
- Local install of the Google Cloud SDK CLI
- Local install of the Terraform CLI
A Terraform Cloud account
- Terraform Cloud organization
- Two new Terraform Cloud workspaces named iac_gke_cluster and iac_kubernetes_app. Choose the "No VCS connection" option
- Enable local execution mode in both the iac_gke_cluster and iac_kubernetes_app workspaces
- Create a new Terraform API token
A Docker Hub account
- Local install of the Docker client
Git clone the Learn infrastructure as code repo from GitHub
A CircleCI account

This post works with the code in the part01 folder of this repo. First though, you need to create GCP credentials and then Terraform.

Creating GCP project credentials

GCP credentials will allow you to perform administrative actions using IaC tooling. To create them:

Go to the create service account key page
Select the default service account or create a new one
Select JSON as the key type
Click Create
Save this JSON file in the ~/.config/gcloud/ directory (you can rename it)

How does HashiCorp Terraform work?

HashiCorp Terraform is an open source tool for building, changing, and versioning infrastructure safely and efficiently. Terraform can manage existing service providers as well as custom in-house solutions.

Terraform uses configuration files to describe the components needed to run a single application or your entire data center. It generates an execution plan describing what it will do to reach the desired state, and then executes it to build the infrastructure described by the plan. As the configuration changes, Terraform determines what changed and creates incremental execution plans which can be applied to update infrastructure resources.

Terraform is used to create, manage, and update infrastructure resources such as physical machines, VMs, network switches, containers, and more. Terraform can manage includes low-level infrastructure components such as compute instances, storage, and networking, as well as high-level components like DNS entries and SaaS features.

Almost any infrastructure type can be represented as a resource in Terraform.

What is a Terraform provider?

A provider is responsible for understanding API interactions and exposing resources. Providers can be an IaaS (Alibaba Cloud, AWS, GCP, Microsoft Azure, OpenStack), a PaaS (like Heroku), or SaaS services (Terraform Cloud, DNSimple, Cloudflare).

In this step, we will provision some resources in GCP using Terraform code. We want to write Terraform code that will define and create a new GKE cluster that we can use in part 2 of the series.

To create a new GKE cluster, we need to rely on the GCP provider for our interactions with GCP. Once the provider is defined and configured, we can build and control Terraform resources on GCP.

What are Terraform resources?

Resources are the most important element in the Terraform language. Each resource block describes one or more infrastructure objects. An infrastructure object can be a virtual network, a compute instance, or a higher-level component like DNS records. A resource block declares a resource of a given type (google_container_cluster) with a given local name like “web”. The name is used to refer to this resource from elsewhere in the same Terraform module, but it has no significance outside of the scope of a module.

Understanding Terraform code

Now that you have a better understanding of Terraform providers and resources, it is time to start digging into the code. Terraform code is maintained within directories. Because we are using the CLI tool, you must execute commands from within the root directories where the code is located. For this tutorial, the Terraform code we are using is located in the part01/iac_gke_cluster folder here. This directory contains these files:

providers.tf
variables.tf
main.tf
output.tf

These files represent the GCP resources infrastructure that we are going to create. These are what Terraform processes. You can place all of the Terraform code into one file, but that can become harder to manage once the syntax grows in volume. Most Terraform devs create a separate file for every element. Here is a quick break down of each file and discuss the critical elements of each.

Breakdown: providers.tf

The provider.tf file is where we define the cloud provider we will use. We will use the google_container_cluster provider. This is the content of the provider.tf file:

provider "google" {
  # version = "2.7.0"
  credentials = file(var.credentials)
  project = var.project
  region = var.region
}

This code block has parameters in closure { } blocks. The credentials block specifies the file path to the GCP credential’s JSON file that you created earlier. Notice that the values for the parameters are prefixed with var. The var prefix defines the usage of Terraform Input Variables, which serve as parameters for a Terraform module. This allows aspects of the module to be customized without altering the module’s own source code, and allows modules to be shared between different configurations. When you declare variables in the root module of your configuration, you can set their values using CLI options and environment variables. When you declare them in child modules, the calling module will pass values in the module block.

Breakdown: variables.tf

The variables.tf file specifies all the input variables that this Terraform project uses.

variable "project" {
  default = "cicd-workshops"
}

variable "region" {
  default = "us-east1"
}

variable "zone" {
  default = "us-east1-d"
}

variable "cluster" {
  default = "cicd-workshops"
}

variable "credentials" {
  default = "~/.ssh/cicd_demo_gcp_creds.json"
}

variable "kubernetes_min_ver" {
  default = "latest"
}

variable "kubernetes_max_ver" {
  default = "latest"
}

The variables defined in this file are used throughout this project. All of these variables have default values, but the values can be changed by defining them with the CLI when executing Terraform code. These variables add much needed flexibility to the code and makes it possible to reuse valuable code.

Breakdown: main.tf

The main.tf file defines the bulk of our GKE cluster parameters.

terraform {
  required_version = "~>0.12"
  backend "remote" {
    organization = "datapunks"
    workspaces {
      name = "iac_gke_cluster"
    }
  }
}

resource "google_container_cluster" "primary" {
  name = var.cluster
  location = var.zone
  initial_node_count = 3

  master_auth {
    username = ""
    password = ""

    client_certificate_config {
      issue_client_certificate = false
    }
  }

  node_config {
    machine_type = var.machine_type
    oauth_scopes = [
      "https://www.googleapis.com/auth/logging.write",
      "https://www.googleapis.com/auth/monitoring",
    ]

    metadata = {
      disable-legacy-endpoints = "true"
    }

    labels = {
      app = var.app_name
    }

    tags = ["app", var.app_name]
  }

  timeouts {
    create = "30m"
    update = "40m"
  }
}

Here is a description for each element of the main.tf file starting with the terraform block. This block specifies the type of Terraform backend. A “backend” in Terraform determines how state is loaded and how an operation such as apply is executed. This abstraction enables things like non-local file state storage and remote execution. In this code block, we are using the remote backend which uses the Terraform Cloud and is connected to the iac_gke_cluster workspace you created in the prerequisites section.

terraform {
  required_version = "~>0.12"
  backend "remote" {
    organization = "datapunks"
    workspaces {
      name = "iac_gke_cluster"
    }
  }
}

The next code block defines the GKE Cluster that we are going to create. We are also using some of the variables defined in variables.tf. The resource block has many parameters used to provision and configure the GKE Cluster on GCP. The important parameters here are name, location, and Initial_node_count, which specifies the initial total of compute resources or virtual machines that will comprise this new cluster. We will start with three compute nodes for this cluster.

resource "google_container_cluster" "primary" {
  name = var.cluster
  location = var.zone
  initial_node_count = 3

  master_auth {
    username = ""
    password = ""

    client_certificate_config {
      issue_client_certificate = false
    }
  }

  node_config {
    machine_type = var.machine_type
    oauth_scopes = [
      "https://www.googleapis.com/auth/logging.write",
      "https://www.googleapis.com/auth/monitoring",
    ]

    metadata = {
      disable-legacy-endpoints = "true"
    }

    labels = {
      app = var.app_name
    }

    tags = ["app", var.app_name]
  }

  timeouts {
    create = "30m"
    update = "40m"
  }
}

Breakdown: output.tf

Terraform uses something called output values. These return values of a Terraform module and provide a child module with outputs. The child module outputs expose a subset of its resource attributes to a parent module, or print certain values in the CLI output after running terraform apply. The output.tf blocks shown in the following code sample output values to readout values like cluster name, cluster endpoint, as well as sensitive data, specified with the sensitive parameter.


output "cluster" {
  value = google_container_cluster.primary.name
}

output "host" {
  value = google_container_cluster.primary.endpoint
  sensitive = true
}

output "cluster_ca_certificate" {
  value = base64decode(google_container_cluster.primary.master_auth.0.cluster_ca_certificate)
  sensitive = true
}

output "username" {
  value = google_container_cluster.primary.master_auth.0.username
  sensitive = true
}

output "password" {
  value = google_container_cluster.primary.master_auth.0.password
  sensitive = true
}

Initializing Terraform

Now that we have covered our Terraform project and syntax, you can start provisioning the GKE cluster using Terraform. Change directory into the part01/iac_gke_cluster folder:

cd part01/iac_gke_cluster

While in part01/iac_gke_cluster, run this command:

terraform init

Your output should be similar to this:

root@d9ce721293e2:~/project/terraform/gcp/compute# terraform init

Initializing the backend...

Initializing provider plugins...
- Checking for available provider plugins...
- Downloading plugin for provider "google" (hashicorp/google) 3.10.0...

* provider.google: version = "~> 3.10"

Terraform has been successfully initialized!

Previewing with Terraform

Terraform has a command that allows you to dry run and validate your Terraform code without actually executing anything. The command is called terraform plan. This command also graphs all the actions and changes that Terraform will execute against your existing infrastructure. In the terminal, run:

terraform plan

The output:

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # google_container_cluster.primary will be created
  + resource "google_container_cluster" "primary" {
      + additional_zones = (known after apply)
      + cluster_ipv4_cidr = (known after apply)
      + default_max_pods_per_node = (known after apply)
      + enable_binary_authorization = false
      + enable_intranode_visibility = (known after apply)
      + enable_kubernetes_alpha = false
      + enable_legacy_abac = false
      + enable_shielded_nodes = false
      + enable_tpu = (known after apply)
      + endpoint = (known after apply)
      + id = (known after apply)
      + initial_node_count = 3
      + instance_group_urls = (known after apply)
      + label_fingerprint = (known after apply)
      + location = "us-east1-d"
  }....
Plan: 1 to add, 0 to change, 0 to destroy.

Terraform will create new GCP resources for you based on the code in the main.tf file.

Terraform apply

Now you can create the new infrastructure and deploy the application. Run this command in the terminal:

terraform apply

Terraform will prompt you to confirm your command. Type yes and press Enter.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

Terraform will build your new GKE cluster on GCP.

Note : It will take 3-5 minutes for the cluster to complete. It is not an instant process because the back-end systems are provisioning and bringing things online.

After my cluster was completed, this was my output:

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

cluster = cicd-workshops
cluster_ca_certificate = <sensitive>
host = <sensitive>
password = <sensitive>
username = <sensitive>

Using Terraform destroy

Now that you have proof that your GKE cluster has been successfully created, run the terraform destroy command to destroy the assets that you created in this tutorial. You can leave it up and running, but be aware that there is a cost associated with any assets running on GCP and you will be liable for those costs. Google gives a generous $300 credit for its free trial sign-up, but you could easily eat through that if you leave assets running. It is up to you, but running terraform destroy will terminate any running assets.

Run this command to destroy the GKE cluster:

terraform destroy

Conclusion

Congratulations! You have just completed part 1 of this series and leveled up your experience by provisioning and deploying a Kubernetes cluster to GCP using IaC and Terraform.

Continue to part 2 of the tutorial. In part 2 you will learn how to build a Docker image for an application, push that image to a repository, and then use Terraform to deploy that image as a container to GKE using Terraform.

Here are a few resources that will help you expand your knowledge:

Smoke testing in CI/CD pipelines

Angel Rivera — Wed, 20 Oct 2021 17:00:00 +0000

Here’s a common situation that plagues many development teams. You run an application through your CI/CD pipeline and all of the tests pass, which is great. But when you deploy it to a live target environment the application just does not function as expected. You can’t always predict what will happen when your application is pushed live. The solution? Smoke tests are designed to reveal these types of failures early by running test cases that cover the critical components and functionality of the application. They also ensure that the application will function as expected in a deployed scenario. When implemented, smoke tests are often executed on every application build to verify that basic but critical functionality passes before jumping into more extensive and time-consuming testing. Smoke tests help create the fast feedback loops that are vital to the software development life cycle.

In this post I’ll demonstrate how to add smoke testing to the deployment stage of a CI/CD pipeline. The smoke testing will test simple aspects of the application post deployment.

Technologies used for smoke testing

This post will reference the following technologies:

Prerequisites

This post relies on configurations and code that are featured in my previous post Automate releases from your pipelines using Infrastructure as Code. The full source code can be found in this repo.

Getting the most from smoke tests

Smoke tests are great for exposing unexpected build errors, connection errors, and for validating a server’s expected response after a new release is deployed to a target environment. For example, a quick, simple smoke test could validate that an application is accessible and is responding with expected response codes like OK 200, 300, 301, 404, etc. The examples in this post will test that the deployed app responds with an OK 200 server code and will also validate that the default page content renders the expected text.

Running CI/CD pipelines without smoke tests

Let’s take a look at an example pipeline config that is designed to run unit tests, build, and push a Docker image to Docker Hub. The pipeline also uses infrastructure as code (Pulumi) to provision a new Google Kubernetes Engine (GKE) cluster and to deploy this release to the cluster. This pipeline config example does not implement smoke tests. Please be aware that if you run this specific pipeline example, a new GKE cluster will be created and will live on until you manually run the pulumi destroy command to terminate all the infrastructure it created.

Caution: Not terminating the infrastructure will result in unexpected costs.

version: 2.1
orbs:
  pulumi: pulumi/pulumi@2.0.0
jobs:
  build_test:
    docker:
      - image: cimg/python:3.8.1
        environment:
          PIPENV_VENV_IN_PROJECT: 'true'
    steps:
      - checkout
      - run:
          name: Install Python Dependencies
          command: |
            pipenv install --skip-lock
      - run:
          name: Run Tests
          command: |
            pipenv run pytest
  build_push_image:
    docker:
      - image: cimg/python:3.8.1
    steps:
      - checkout
      - setup_remote_docker:
          docker_layer_caching: false
      - run:
          name: Build and push Docker image
          command: |       
            pipenv install --skip-lock
            pipenv run pip install --upgrade 'setuptools<45.0.0'
            pipenv run pyinstaller -F hello_world.py
            echo 'export TAG=${CIRCLE_SHA1}' >> $BASH_ENV
            echo 'export IMAGE_NAME=orb-pulumi-gcp' >> $BASH_ENV
            source $BASH_ENV
            docker build -t $DOCKER_LOGIN/$IMAGE_NAME -t $DOCKER_LOGIN/$IMAGE_NAME:$TAG .
            echo $DOCKER_PWD | docker login -u $DOCKER_LOGIN --password-stdin
            docker push $DOCKER_LOGIN/$IMAGE_NAME
  deploy_to_gcp:
    docker:
      - image: cimg/python:3.8.1
        environment:
          CLOUDSDK_PYTHON: '/usr/bin/python2.7'
          GOOGLE_SDK_PATH: '~/google-cloud-sdk/'
    steps:
      - checkout
      - pulumi/login:
          version: "2.0.0"
          access-token: ${PULUMI_ACCESS_TOKEN}
      - run:
          name: Install dependencies
          command: |
            cd ~/
            pip install --user -r project/requirements.txt
            curl -o gcp-cli.tar.gz https://dl.google.com/dl/cloudsdk/channels/rapid/google-cloud-sdk.tar.gz
            tar -xzvf gcp-cli.tar.gz
            echo ${GOOGLE_CLOUD_KEYS} | base64 --decode --ignore-garbage > ${HOME}/project/pulumi/gcp/gke/cicd_demo_gcp_creds.json
            ./google-cloud-sdk/install.sh --quiet
            echo 'export PATH=$PATH:~/google-cloud-sdk/bin' >> $BASH_ENV
            source $BASH_ENV
            gcloud auth activate-service-account --key-file ${HOME}/project/pulumi/gcp/gke/cicd_demo_gcp_creds.json
      - pulumi/update:
          stack: k8s
          working_directory: ${HOME}/project/pulumi/gcp/gke/
workflows:
  build_test_deploy:
    jobs:
      - build_test
      - build_push_image
      - deploy_to_gcp:
          requires:
          - build_test
          - build_push_image

This pipeline deploys the new app release to a new GKE cluster, but we do not know if the application is actually up and running after all of this automation completes. How do we find out whether the application has been deployed and is functioning properly in this new GKE cluster? Smoke tests are a great way to quickly and easily validate the application’s status after deployment.

How do I write a smoke test?

The first step is to develop test cases that define the steps required to validate an application’s functionality. Identify the functionality that you want to validate, and then create scenarios to test it. In this tutorial, I’m intentionally describing a very minimal scope for testing. For our sample project, my biggest concern is validating that the application is accessible after deployment and that the default page that is served renders the expected static text.

I prefer to outline and list the items I want to test because it suits my style of development. The outline shows the factors I considered when developing the smoke tests for this app. Here is an example of how I developed test cases for this smoke test:

What language/test framework?
- Bash
- smoke.sh
When should this test be executed?
- After the GKE cluster has been created
What will be tested?
- Test: Is the application accessible after it is deployed?
- Expected Result: Server responds with code 200
- Test: Does the default page render the text “Welcome to CI/CD”
- Expected Result: TRUE
- Test: Does the default page render the text “Version Number: “
- Expected Results: TRUE
Post test actions (must occur regardless of pass or fail)
- Write test results to standard output
- Destroy the GKE cluster and related infrastructure
- Run pulumi destroy

My test case outline (also called a test script) is complete for this tutorial and clearly shows what I’m interested in testing. For this post, I will write smoke tests using a bash-based, open source smoke test framework called smoke.sh by asm89. For your own projects, you can write smoke tests in what ever language or framework you prefer. I picked smoke.sh because it’s an easy framework to implement and it’s open source. Now let’s explore how to express this test script using the smoke.sh framework.

Create smoke test using smoke.sh

The smoke.sh framework’s documentation describes how to use it. The next block of sample code shows how I used the smoke_test file found in the test/ directory of the example code’s repo.

#!/bin/bash

. tests/smoke.sh

TIME_OUT=300
TIME_OUT_COUNT=0
PULUMI_STACK="k8s"
PULUMI_CWD="pulumi/gcp/gke/"
SMOKE_IP=$(pulumi stack --stack $PULUMI_STACK --cwd $PULUMI_CWD output app_endpoint_ip)
SMOKE_URL="http://$SMOKE_IP"

while true
do
  STATUS=$(curl -s -o /dev/null -w '%{http_code}' $SMOKE_URL)
  if [$STATUS -eq 200]; then
    smoke_url_ok $SMOKE_URL
    smoke_assert_body "Welcome to CI/CD"
    smoke_assert_body "Version Number:"
    smoke_report
    echo "\n\n"
    echo 'Smoke Tests Successfully Completed.'
    echo 'Terminating the Kubernetes Cluster in 300 second...'
    sleep 300
    pulumi destroy --stack $PULUMI_STACK --cwd $PULUMI_CWD --yes
    break
  elif [[$TIME_OUT_COUNT -gt $TIME_OUT]]; then
    echo "Process has Timed out! Elapsed Timeout Count.. $TIME_OUT_COUNT"
    pulumi destroy --stack $PULUMI_STACK --cwd $PULUMI_CWD --yes
    exit 1
  else
    echo "Checking Status on host $SMOKE... $TIME_OUT_COUNT seconds elapsed"
    TIME_OUT_COUNT=$((TIME_OUT_COUNT+10))
  fi
  sleep 10
done

Next, I’ll explain what’s going on in this smoke_test file.

Line by line description of the smoke_test file

Let’s start at the top of the file.

#!/bin/bash

. tests/smoke.sh

This snippet specifies the Bash binary to use and also specifies the file path to the core smoke.sh framework to import/include in the smoke_test script.

TIME_OUT=300
TIME_OUT_COUNT=0
PULUMI_STACK="k8s"
PULUMI_CWD="pulumi/gcp/gke/"
SMOKE_IP=$(pulumi stack --stack $PULUMI_STACK --cwd $PULUMI_CWD output app_endpoint_ip)
SMOKE_URL="http://$SMOKE_IP"

This snippet defines environment variables that will be used throughout the smoke_test script. Here is a list of each environment variable and its purpose:

PULUMI_STACK="k8s" is used by Pulumi to specify the Pulumi app stack.
PULUMI_CWD="pulumi/gcp/gke/" is the path to the Pulumi infrastructure code.
SMOKE_IP=$(pulumi stack --stack $PULUMI_STACK --cwd $PULUMI_CWD output app_endpoint_ip) is the Pulumi command used to retrieve the public IP address of the application on the GKE cluster. This variable is referenced throughout the script.
SMOKE_URL="http://$SMOKE_IP" specifies the url endpoint of the application on the GKE cluster.

while true
do
  STATUS=$(curl -s -o /dev/null -w '%{http_code}' $SMOKE_URL)
  if [$STATUS -eq 200]; then
    smoke_url_ok $SMOKE_URL
    smoke_assert_body "Welcome to CI/CD"
    smoke_assert_body "Version Number:"
    smoke_report
    echo "\n\n"
    echo 'Smoke Tests Successfully Completed.'
    echo 'Terminating the Kubernetes Cluster in 300 second...'
    sleep 300
    pulumi destroy --stack $PULUMI_STACK --cwd $PULUMI_CWD --yes
    break
  elif [[$TIME_OUT_COUNT -gt $TIME_OUT]]; then
    echo "Process has Timed out! Elapsed Timeout Count.. $TIME_OUT_COUNT"
    pulumi destroy --stack $PULUMI_STACK --cwd $PULUMI_CWD --yes
    exit 1
  else
    echo "Checking Status on host $SMOKE... $TIME_OUT_COUNT seconds elapsed"
    TIME_OUT_COUNT=$((TIME_OUT_COUNT+10))
  fi
  sleep 10
done

This snippet is where all the magic happens. It’s a while loop that executes until a condition is true or the script exits. In this case, the loop uses a curl command to test if the application returns an OK 200 response code. Because this pipeline is creating a brand new GKE cluster from scratch, there are transactions in the Google Cloud Platform that need to be complete before we begin smoke testing.

The GKE cluster and application service must be up and running.
The $STATUS variable is populated with the results of the curl requests then tested for the value of 200. Otherwise, the loop increments the $TIME_OUT_COUNT variable by 10 seconds, then waits for 10 seconds to repeat the curl request until the application is responding.
Once the cluster and app are up, running, and responding, the STATUS variable will produce a 200 response code and the remainder of the tests will proceed.

The smoke_assert_body "Welcome to CI/CD" and smoke_assert_body "Version Number: " statements are where I test that the welcome and version number texts are being rendered on the webpage being called. If the result is false, the test will fail, which will cause the pipeline to fail. If the result is true, then the application will return a 200 response code and our text tests will result in TRUE. Our smoke test will pass and execute the pulumi destroy command that terminates all of the infrastructure created for this test case. Since there is no further need for this cluster, it will terminate all the infrastructure created in this test.

This loop also has an elif (else if) statement that checks to see if the application has exceeded the $TIME_OUT value. The elif statement is an example of exception handling which enables us to control what happens when unexpected results occur. If the $TIME_OUT_COUNT value exceeds the TIME_OUT value, then the pulumi destroy command is executed and terminates the newly created infrastructure. The exit 1 command then fails your pipeline build process. Regardless of test results, the GKE cluster will be terminated because there really isn’t a need for this infrastructure to exist outside of testing.

Adding smoke tests to pipelines

I’ve explained the smoke test example and my process for developing the test case. Now it’s time to integrate it into the CI/CD pipeline configuration above. We’ll add a new run step below the pulumi/update step of the deploy_to_gcp job:

      ...
      - run:
          name: Run Smoke Test against GKE
          command: |
            echo 'Initializing Smoke Tests on the GKE Cluster'
            ./tests/smoke_test
            echo "GKE Cluster Tested & Destroyed"
      ...

This snippet demonstrates how to integrate and execute the smoke_test script into an existing CI/CD pipeline. Adding this new run block ensures that every pipeline build will test the application on a live GKE cluster and provide a validation that the application passed all test cases. You can be confident that the specific release will perform nominally when deployed to the tested target environment which in this case, is a Google Kubernetes cluster.

Wrapping up

In summary, I’ve discussed and demonstrated the advantages of using smoke tests and Infrastructure as Code in CI/CD pipelines to test builds in their target deployment environments. Testing an application in its target environment provides valuable insight into how it will behave when it’s deployed. Integrating smoke testing into CI/CD pipelines adds another layer of confidence in application builds.

If you have any questions, comments, or feedback please feel free to ping me on Twitter @punkdata.

Thanks for reading!

Managing reusable pipeline configuration with object parameters

Angel Rivera — Fri, 08 Oct 2021 16:00:00 +0000

CircleCI pipelines are defined using the YAML syntax, which has been widely adopted by many software tools and solutions. YAML is a human-readable declarative data structure used in in configuration files (like those for CircleCI pipelines) and in applications where data is being stored or transmitted. The data in pipeline configuration files specifies and controls how workflows and jobs are executed when triggered on the platform. These pipeline directives in configuration files tend to become repetitive, which can result in situations where the config syntax grows in volume. Over time, this increased volume makes the config harder to maintain. Because YAML is a data structure, only minimal syntax reusability capabilities (Anchors and Aliases) are available to address the increased volume. Anchors and Aliases are too limited to be useful for defining CI/CD pipelines. Fortunately, CircleCI configuration parameter features provide robust capabilities for encapsulating and reusing functionality data that would otherwise be redundant.

In this post, I will introduce pipeline configuration parameters and explain some of the benefits of adopting them in your pipeline configurations.

What are configuration parameters?

Executors, jobs and commands are considered objects within a pipeline configuration file. Like objects in the Object Oriented Programming (OOP) paradigm, pipeline objects can be extended to provide customized functionality. CircleCI configuration parameters let developers extend the capabilities of executors, jobs, and commands by providing ways to create, encapsulate, and reuse pipeline configuration syntax.

Executors, jobs, and commands are objects with their own individual properties. Parameters also have their own distinct properties that can interact with the object. The composition and properties for parameters include:

parameters:
  |_ parameter name: (Specify a name the parameter)
    |_ description: (Optional. Describes the parameter)
    |_ type: (Required. datatype string, boolean, integer, enum)
    |_ default: (The default value for the parameter)

When should I use parameters in a pipeline config?

Use parameters when data and functionality is repeated within pipelines. In other words, if your pipelines have any executors, jobs, or commands that are defined or executed in your pipelines more than once, I recommend identifying those patterns or elements and defining them as parameters within your configuration file syntax. Using parameters gives you the ability to centrally manage and maintain functionality, and dramatically minimizes redundant data and the total lines of syntax in configuration files. The ability to provide variable parameter arguments is also a benefit, and the overall readability of the pipeline syntax is improved as well.

How do I create parameters?

As I mentioned earlier, executors, jobs, and commands are the configuration elements that can be extended with parameters. Deciding which of these elements to extend will depend on your specific use case.

NOTE: The parameters features are available only in CircleCI version 2.1 and above. The version must be defined at the top of the config file like this: version: 2.1 for the parameters to be recognized by the platform.

Let me give you an example of defining a parameter for the parallelism quantities within a jobs: object:

version: 2.1
jobs:
  build_artifact:
    parameters:
      parallelism_qty:
        type: integer
        default: 1
    parallelism: << parameters.parallelism_qty >>
    machine: true
    steps:
      - checkout
workflows:
  build_workflow:
    jobs:
      - build_artifact:
          parallelism_qty: 2

In this example, the build-artifact: job has a parameters: key defined with the name parallelism_qty:. This parameter has a data type of integer, and a default value of 1. The parallelism: key is a property of the jobs: object and defines the number of executors to spawn and execute commands in the steps: list. In this case, the special checkout command will be executed on all the executors spawned. The job’s parallelism: key has been assigned the value « parameters.parallelism\_qty », which references the parallelism\_qty: parameter definition defined above it. This example shows how parameters can add flexibility to your pipeline constructs, and provide a convenient way to centrally manage functionality that is repeated in pipeline syntax.

Using parameters in job objects

Using the previous example, the parallelism_qty: parameter in the workflow block demonstrates how to use parameters within configuration syntax. Because the parallelism_qty: is defined in a job object, it can be executed as a job specified in a workflow.

The workflows: block has a jobs: list that specifies the build_artifact:. It also assigns a value of 2 executors to the parallelism_qty:, which will spawn 2 executors and execute the commands in the steps: list. If that value was 3, then the build_artifact job would spawn 3 executors and run the commands 3 times.

Executors, jobs, and commands are objects with properties that can be defined, customized, and reused throughout pipeline configuration syntax.

Reusing executor objects in pipeline config

The previous section demonstrates how to define and use parameters within a jobs object. In this section, I will describe how to use parameters with executors. Executors define the runtime or environment used to execute pipeline jobs and commands. Executor objects have a set of their own unique properties that parameters can interact with. This is an example of defining and implementing reusable executors:

version: 2.1
executors:
  docker-executor:
    docker:
      - image: cimg/ruby:3.0.2-browsers
   ubuntu_20-04-executor:
    machine:
      image: 'ubuntu-2004:202010-01'
jobs:
  run-tests-on-docker:
    executor: docker-executor
    steps:
      - checkout
      - run: ruby unit_test.rb 
  run-tests-on-ubuntu-2004:
    executor: ubuntu_20-04
    steps:
      - checkout
      - run: ruby unit_test.rb 
workflows:
  test-app-on-diff-os:
    jobs:
      - run-tests-on-docker
      - run-tests-on-ubuntu-2004

This example shows how to define and implement reusable executors in your pipeline config. I used the executors: key at the start of the file to define 2 executors, one named docker-executor: and one called ubuntu_20-04-executor:. The first specifies using a Docker executor and the second specifies a machine executor using an Ubuntu 20.04 operating system image. Predefining executors this way enables developers to create a list of executor resources to be used in this pipeline, and to centrally manage the various properties related to executor types. For instance, the Docker executor has properties that do not pertain to and are unavailable to the machine executor, because the machine executor is not of the type docker.

Reusing objects keeps the amount of syntax to minimum while providing terse object implementations that optimize code readability and central management of functionality.

The jobs: block defines run-tests-on-docker: and run-tests-on-ubuntu-2004:; both have a an executor: key specified with a value assigned as the appropriate executor for that job. The run-tests-on-docker: job executes its steps using the docker-executor definition and the run-tests-on-ubuntu-2004: job executes on the ubuntu_20-04 definition. As you can see, pre-defining these executors in their own stanza makes the config syntax easier to read, which will make it easier to use and maintain. Any changes to executors can be made in the respective definition and will propagate to any jobs that implement them. This type of centralized management of defined executors can also apply to jobs and command objects that are defined in a similar way.

In the workflows: block, the test-app-on-diff-os: workflow triggers two jobs in parallel that execute unit-tests in their respective executor environments. Running these tests using different executors is helpful when you want to find out how applications will behave in different operating systems. This type of test is common practice. The take away here is that I defined the executors just once and easily implemented them within multiple jobs.

Reusable command objects

Commands can also be defined and implemented within config syntax, just like executors and jobs can. Although command object properties differ from executors and jobs, defining and implementating them is similar. Here is an example showing reusable commands:

version: 2.1

commands:
  install-wget:
    description: "Install the wget client"
    parameters:
      version:
        type: string
        default: "1.20.3-1ubuntu1"
    steps:
      - run: sudo apt install -y wget=<< parameters.version >>
jobs:
  test-web-site:
    docker:
      - image: "cimg/base:stable"
        auth:
          username: $DOCKERHUB_USER
          password: $DOCKERHUB_PASSWORD
    steps:
      - checkout
      - install-wget:
          version: "1.17.0-1ubuntu1"
      - run: wget --spider https://www.circleci.com
workflows:
  run-tests:
    jobs:
      - test-web-site

In this example, a reusable command has been defined and implemented by a job. The command: key at the top of of the config defines a command named install-wget: that installs a specific version of the wget client. In this case, a parameter is defined to specify which wget version number to install. The default: key installs the default value of 1.20.3-1ubuntu1 if a value is not specified. The steps: key lists 1 run: command that installs the version of wget specified in the versions: parameter. The versions: parameter is referenced by the << parameters.version >> variable.

As shown in the example, the defined command can be implemented and used by job objects. The steps stanza in the test-web-site: job implements the - install-wget: command. Its version: parameter is set to an earlier, older version of wget, not the default version value. The last run: command in the job uses wget to test a response from the given URL. This example runs a simple test to check if a website is responding to requests.

The workflows: block, as usual, triggers the - test-web-site job, which executes the reusable install-wget command. Just like executors and jobs, commands bring the ability to reuse code, centrally manage changes, and increase the readability of the syntax within pipeline configuration files.

Conclusion

In this post, I described the basics of using pipeline parameters and reusable pipeline objects: executors, jobs, and commands. The key takeaways:

Executors, jobs, and commands are considered objects with properties that can be defined, customized, and reused throughout pipeline configuration syntax
Reusing these objects helps keep the amount of syntax to minimum while providing terse object implementations that optimize code readability and central management of functionality

Although I wrote this post to introduce you to the concepts of parameters and reusable objects, I would like to encourage you to review the Reusable Config Reference Guide. It will help you gain a deeper understanding of these capabilities so that you can to take full advantage of these awesome features.

I would love to know your thoughts and opinions, so please join the discussion by tweeting to me @punkdata.

Thanks for reading!

Deploy applications using CircleCI, Docker, HashiCorp Terraform, and Google Cloud

Angel Rivera — Thu, 13 Dec 2018 18:00:00 +0000

I regularly speak at conferences and tech meetups, and lately I’ve been fielding a lot of questions regarding the continuous delivery of applications to cloud platforms, such as Google Cloud, using HashiCorp Terraform. In this post, I will demonstrate how to deploy an application using CI/CD pipelines, Docker, and Terraform into a Google Cloud instance. In this example, you will create a new Google Cloud instance using a Google Container-Optimized OS host image. Google’s Container-Optimized OS is an operating system image for Compute Engine VMs that is optimized for running Docker containers. With Container-Optimized OS, you can bring your Docker containers up on Google Cloud Platform quickly, efficiently, and securely.

This tutorial also demonstrates how to use Terraform to create a new Google Cloud instance and deploy the application using this CI/CD tutorial Docker image. The image will be pulled from Docker Hub and run on the instance created from Terraform.

Prerequisites

Before you get started you'll need to have the following:

You'll also need to:

Fork or clone the cicd-101-workshop repo locally.
Complete the hands on with CircleCI section in this tutorial, specifically the setting your Docker Hub credential environment variables section, which is required for the build to push the Docker image to Docker Hub.
Ensure that a your application's Docker image exists in your Docker Hub account. A green build on CircleCI should get you there.

After you have all the prerequisites, you're ready to proceed to the next section.

Infrastructure as code

Infrastructure as code (IaC) is the process of managing and provisioning cloud and IT resources via machine readable definition files. IaC enables organizations to provision, manage, and destroy compute resources using modern DevOps tools such as Terraform.

You'll be using IaC principles and Terraform in this post to deploy your application to Google Cloud.

Create a Google Cloud Platform project

Use these instructions to create a new Google Cloud project.

Create and get Google Cloud Project credentials

You will need to create Google Cloud credentials in order to perform administrative actions using Terraform. Go to the Create Service Account Key page. Select the default service account or create a new one, select JSON as the key type, and click Create. Save this JSON file in the root of terraform/google_cloud/.

Important security note: Rename the file to cicd_demo_gcp_creds.json in order to protect your Google Cloud credentials from being published and exposed in a public GitHub repository. You can also protect the credential's JSON file from being released by simply adding the credential's JSON filename in this project's .gitignore file. You must be very cautious with the data in this JSON file because, if exposed, anyone with this information can hack into your Google Cloud account, create resources, and run up charges.

Install Terraform locally

First, install Terraform locally.

Set up Terraform

In a terminal, run:

cd terraform/google_cloud/
terraform init # this installs the Google Terraform plugins

Next, you'll have to change some values in the main.tf file. You'll change the values of the Terraform variables to match your information. Change the variable project_name's default tag to the project name you created earlier:

variable "project_name" {
  type = "string"
  default = "cicd-workshops"
}

Change the variable docker_declaration's default tag's image value of: image: 'ariv3ra/python-cicd-workshop' to the Docker image that you built and pushed to Docker Hub in the CI/CD tutorial:

variable "docker_declaration" {
  type = "string"
  # Change the image: string to match the Docker image you want to use
  default = "spec:\n  containers:\n    - name: test-docker\n      image: 'ariv3ra/python-cicd-workshop'\n      stdin: false\n      tty: false\n  restartPolicy: Always\n"
}

Terraform plan

The terraform plan command is used to create an execution plan. Terraform performs a refresh, unless explicitly disabled, and then determines what actions are necessary to achieve the desired state specified in the configuration files. This command is a convenient way to check whether the execution plan for a set of changes matches your expectations without making any changes to real resources or to the state.

In a terminal, run:

terraform plan -out=plan.txt

This will show you a nice graph that lists which items Terraform will create or change.

Terraform apply

The terraform apply command is used to apply the changes required to reach the desired state of the configuration, or the pre-determined set of actions generated by a Terraform execution plan.

In a terminal, run:

terraform apply plan.txt

This executes the Terraform plan and attempts to build out a new Google Compute instance based on the plan and the Docker image defined.

Google Compute instance IP address

When Terraform completes building the Google assets, you should see the instance's Public IP Address and it should look similar to the output below:

Public IP Address = 104.196.11.156

Copy the IP Address or DNS listed and paste it into a web browser with port 5000 appended to the end. The complete address should look like this:

https://35.237.090.42:5000

The new application should render a welcome message and an image. The application is a Docker container spawned from the CI/CD intro tutorial Docker image you built and pushed to CircleCI.

Terraform destroy

Now that you have proof that your Google Compute instance and your Docker container work, you should run the terraform destroy command to destroy the assets that you created in this tutorial. You can leave it up and running, but be aware that there is a cost associated with any assets running in the Google Cloud Platform and you could be liable for those costs. Google gives a generous $300 credit for its free trial sign-up, but you could easily eat through that if you leave assets running. It's up to you, but running terraform destroy will close out any running assets.

Summary

In this post, you deployed the example application to a live Google Cloud instance from Docker Hub using Terraform. This example demonstrates how to manually deploy your applications using Terraform after the application's CI/CD pipeline builds green on CircleCI. With some additional tweaking of the project's CircleCI config.yml file, you can configure the CI/CD pipeline to automatically deploy using Terraform within the pipeline. Configuring automatic Terraform deployments are a bit more complicated and require a bit more engineering but it's definitely possible. It might be a topic for a future blog pos, so stay tuned!

If you want to learn more about CircleCI check out the documentation site. If you get stuck, you can reach out to the CircleCI community via the community forum.