Skip to main content

Kubernetes deployments

This topic shows you how to deploy a publicly-available NGINX Docker image and manifest into your Kubernetes cluster using a rolling update strategy in Harness.

Objectives​

You'll learn how to:

  • Install and launch a Harness Kubernetes Delegate in your target cluster.
  • Set up a Kubernetes Pipeline.
  • Run the new Kubernetes Pipeline and deploy a Docker image to your target cluster.

Before you begin​

Make sure you have the following set up before you begin this quickstart:

  • GitHub account: this quickstart uses a publicly available NGINX manifest and Docker image. DockerHub allows anonymous connections, but GitHub requires that you log into your account to access their repos.

Set up your Kubernetes cluster​

You'll need a target Kubernetes cluster for the Harness Delegate and deployment. Ensure your cluster meets the following requirements:

  • Number of nodes: 2.
  • vCPUs, Memory, Disk Size: 4vCPUs, 16GB memory, 100GB disk. In GKE, the e2-standard-4 machine type is enough for this quickstart.
  • Networking: outbound HTTPS for the Harness connection to app.harness.io, github.com, and hub.docker.com. Allow TCP port 22 for SSH.
  • A Kubernetes service account with permission to create entities in the target namespace is required. The set of permissions should include list, get, create, and delete permissions. In general, the cluster-admin permission or namespace admin permission is enough.
    For more information, see User-Facing Roles from Kubernetes.

Create the deploy stage​

Pipelines are collections of stages. For this tutorial, we'll create a new pipeline and add a single stage.

note

Create a Project for your new CD Pipeline: if you don't already have a Harness project, create a project for your new CD pipeline. Ensure that you add the Continuous Delivery module to the project. Go to create organizations and projects for more information.

  1. In your Harness project, select Deployments, and then select Create a Pipeline.

  2. Enter the name CD Quickstart and select Start.

    Your pipeline appears.

  3. Select Add Stage and select Deploy.

  4. Enter the name Deploy Service, make sure Service is selected, and then select Set Up Stage.

    The new stage settings appear.

  5. In About the Service, select New Service.

    note

    Let's take a moment and review Harness services and service definitions (which are explained below). Harness services represent your microservices/apps logically. You can add the same service to as many stages as you need. Service definitions represent your artifacts, manifests, and variables physically. They are the actual files and variable values.

    By separating services and service definitions, you can propagate the same Service across stages while changing the artifacts, manifests, and variables with each stage.

  6. Give the service the name nginx and select Save.

Once you have created a service, it is persistent and can be used throughout the stages of this or any other pipeline in the project.

Add the manifest​

Next, we can add a Kubernetes manifest for NGINX. We'll use the publicly-available manifest available from Kubernetes.

  1. In Service Definition, in Deployment Type, select Kubernetes.

  2. In Manifests, select Add Manifest.

    note

    What about Artifacts? In this quickstart we are using a publicly-available NGINX Docker image from DockerHub, and the location of the image is hardcoded in the public manifest from Kubernetes. The Artifacts section is only used when the public artifact is not hardcoded in the manifest or the repo is private. In those cases, you add the image in Artifacts with a Connector for the repo and then reference the image in your values.yaml (image: <+artifact.image>). See Add Container Images as Artifacts for Kubernetes Deployments.

  3. Select K8s Manifest, and select Continue.

  4. In Select K8sManifest Store, select GitHub, and then select New GitHub Connector.

  5. The Git Connector settings appear. Enter the following settings.

    • Name: enter a name for the connector.

    • URL Type: select Repository.

    • Connection Type: select HTTP.

    • Git Repository URL: enter https://github.com/kubernetes/website.

    • Username and Token: Enter the username and a Github Personal Access Token (PAT) for your GitHub account. You'll have to create a Harness secret for the password.

      1. In Personal Access Token, click Create or Select a Secret.
      2. Select New Secret Text.
      3. In Secret Name, enter a name for the secret like github-pat.
      4. In Secret Value, paste in a GitHub Personal access token. When you're logged into GitHub, these are typically listed at https://github.com/settings/tokens. For steps on setting up a GitHub PAT, go to creating a personal access token from GitHub. Ensure you PAT has the repo scope selected:

  6. Select Continue.

  7. In Connect to the provider, select Connect through a Harness Delegate, and then select Continue. We don't use the Connect through Harness Platform option here simply because you'll need a Delegate later for the connection to your target Kubernetes cluster. Typically, the Connect through Harness Platform option is a very quick way to make connections without having to use Delegates.

    Expand the section below to learn more about installing delegates.

    Install a new delegate

    1. In Delegates Setup, select Install new Delegate. The delegate wizard appears.

    2. In the New Delegate dialog, in Select where you want to install your Delegate, select Kubernetes.

    3. In Install your Delegate, select Kubernetes Manifest.

    4. Enter a delegate name.

      • Delegate names must be unique within a namespace and should be unique in your cluster.
      • A valid name includes only lowercase letters and does not start or end with a number.
      • The dash character (“-”) can be used as a separator between letters.

    5. At a terminal, run the following cURL command to copy the Kuberntes YAML file to the target location for installation.

      curl -LO https://raw.githubusercontent.com/harness/delegate-kubernetes-manifest/main/harness-delegate.yaml

    6. Open the harness-delegate.yaml file. Find and specify the following placeholder values as described.

      ValueDescription
      PUT_YOUR_DELEGATE_NAMEName of the delegate.
      PUT_YOUR_ACCOUNT_IDHarness account ID.
      PUT_YOUR_MANAGER_ENDPOINTURL of your cluster. See the following table of Harness clusters and endpoints.
      PUT_YOUR_DELEGATE_TOKENDelegate token. To find it, go to Account Settings > Account Resources, select Delegate, and select Tokens. For more information on how to add your delegate token to the harness-delegate.yaml file, go to Secure delegates with tokens.

      Your Harness manager endpoint depends on your Harness SaaS cluster location. Use the following table to find the Harness manager endpoint in your Harness SaaS cluster.

      Harness cluster locationHarness Manager endpoint
      SaaS prod-1https://app.harness.io
      SaaS prod-2https://app.harness.io/gratis
      SaaS prod-3https://app3.harness.io

    7. Install the delegate by running the following command:

      kubectl apply -f harness-delegate.yaml

      The successful output looks like this.

      namespace/harness-delegate-ng unchanged
      clusterrolebinding.rbac.authorization.k8s.io/harness-delegate-cluster-admin unchanged
      secret/cd-doc-delegate-account-token created
      deployment.apps/cd-doc-delegate created
      service/delegate-service configured
      role.rbac.authorization.k8s.io/upgrader-cronjob unchanged
      rolebinding.rbac.authorization.k8s.io/upgrader-cronjob configured
      serviceaccount/upgrader-cronjob-sa unchanged
      secret/cd-doc-delegate-upgrader-token created
      configmap/cd-doc-delegate-upgrader-config created
      cronjob.batch/cd-doc-delegate-upgrader-job created

    8. Select Verify to make sure that the delegate is installed properly.

  8. Back in Set Up Delegates, you can select the new Delegate. In the list of Delegates, you can see your new Delegate and its tags.

  9. Select the Connect using Delegates with the following Tags option.

  10. Enter the tag of the new Delegate and select Save and Continue. When you are done, the Connector is tested.

  11. Select Continue.

  12. In Manifest Details, enter the following settings, test the connection, and click Submit. We are going to provide connection and path information for a manifest located at https://raw.githubusercontent.com/kubernetes/website/main/content/en/examples/application/nginx-app.yaml.

  • Manifest Identifier: enter nginx.

  • Git Fetch Type**: select Latest from Branch**.

  • Branch: enter main.

  • File/Folder path:content/en/examples/application/nginx-app.yaml. This is the path from the repo root.

    The manifest is now listed.

  1. Select Next at the bottom of the Service tab.

Now that the artifact and manifest are defined, you can define the target cluster for your deployment.

Define your target cluster​

The target cluster is your own Kubernetes cluster, hosted in your cloud environment. This is where we will deploy the Docker image using the manifest you selected.

Harness connects to all of the common cloud platforms and provides a platform-agnostic Kubernetes cluster connection that can connect to Kubernetes anywhere.

  1. In Infrastructure Details, in Specify your environment, select New Environment. Just like with a service, you can create a new environment or selecting an existing one. We'll create a new one.

  2. In New Environment, enter a name, select Pre-Production, and select Save. The new environment appears.

  3. In Infrastructure Definition, select Kubernetes.

    note

    Let's take a moment and review Harness environments and infrastructure definitions. Harness environments represent your deployment targets logically (QA, Prod, etc). You can add the same Environment to as many stages as you need. Infrastructure definitions represent your target infrastructure physically. They are the actual clusters, hosts, etc.

    By separating environments and infrastructure definitions, you can use the same environment in multiple stages while changing the target infrastructure settings with each stage.

  4. An Infrastructure Definition is where you specify the target for your deployment. In this case, your Kubernetes cluster and namespace.

  5. In Cluster Details, in Connector, select Select a connector.

  6. Select New Connector.

  7. The Kubernetes cluster connector appears.

The Kubernetes cluster connector is covered in detail here, but let's quickly walk through it.

Let's look at the steps:

  1. In Kubernetes Cluster Connector, in Name, enter Kubernetes Quickstart, and select Continue.

  2. In Details, select Use the credentials of a specific Harness Delegate. We will select the Delegate next.

  3. Select Continue.

  4. Select the Kubernetes Delegate you added earlier using its Tags, and then select Save and Continue. Harness verifies the Connector.

  5. Select Finish.

  6. Select the new Connector and then select Apply Selected.

  7. Back in Cluster Details, in Namespace, enter the target namespace for the deployment. For example, default. You can use any namespace in your target cluster.

  8. In Advanced, in Release name, enter quickstart. For a release name, you can use a built-in or custom expression or any text you like. Harness requires a release name for tracking. It is applied to the pods as a label. The release name must be unique across the cluster.

  9. When you are done, the Cluster Details will look something like this:

    The target infrastructure is complete. Now we can add our stage steps.

  10. Select Next to move onto Execution.

Add a rollout deployment Step​

Now you can select the deployment strategy for this stage of the pipeline.

  1. In Execution Strategies, select Rolling, and then select Use Strategy.

  2. The Rollout Deployment step is added.

    This is a standard Kubernetes rolling update. By default, Harness uses a 25% max unavailable, 25% max surge strategy.

That's it. Now the pipeline stage is complete and you can deploy.

Deploy and review​

  1. Select Save > Save Pipeline and then Run. Now you can select the specific artifact to deploy.

  2. In Primary Artifact, select stable. This is the same as using docker pull nginx:stable.

  3. Select Run Pipeline. Harness will verify the Pipeline and then run it. You can see the status of the deployment, and pause or abort it.

  4. Toggle Console View to watch the deployment with more detailed logging. Select the Rollout Deployment step and expand Wait for Steady State.

    You can see deployment "my-nginx" successfully rolled out.

Congratulations! The deployment was successful.

In your project's Deployments, you can see the deployment listed:

If you run into any errors, it is typically because the cluster does meet the requirements from Before You Begin section or the cluster's network setting does not allow the Delegate to connect to Docker Hub.In this tutorial, you learned how to:

  • Install and launch a Harness Kubernetes Delegate in your target cluster.
  • Connect Harness to your Kubernetes cluster and an artifact server.
  • Add your manifests to Harness.
  • Create an infrastructure definition that targets your cluster and namespace.
  • Add a Kubernetes rolling update.
  • Deploy your Kubernetes pipeline to your target cluster.

Next, try Harness Continuous Integration to build a codebase, upload it to a repo, and run unit and integrations tests: CI pipeline quickstart.

Clean Up​

For steps on deleting the Delgate, go to delete a delegate.

Next Steps​

See CD tutorials for other deployment features.