Skip to main content

Kubernetes services

Last updated on

A Harness service for Kubernetes represents the application you want to deploy. It holds the manifests, artifact sources, override files, and sidecar definitions that Harness uses to deploy to your cluster.

Services are independent of pipelines; configure one once and reuse them across stages and pipelines.

Before you begin​

  • Kubernetes cluster access: A running cluster that your Harness delegate can reach. Go to Install a Kubernetes delegate to set up a delegate in your cluster.
  • Source connector: A connector to the repository or registry where your manifest files and container images are stored. Go to Connect to a code repo to set up a Git connector.
  • Harness project: A project with CD enabled. Go to Create organizations and projects to create one.

Create a Kubernetes service​

  1. Go to Deployments, expand the drop-down, and select Services under Resources.
  2. Click Create Service.
  3. In the Create service panel, select Kubernetes from the Deployment Target drop-down.
  4. Harness auto-generates a name and ID. You can change both.
  5. Under Storage, select Inline (Harness stores the service configuration) or a Git repository.
  6. Configure manifests, additional override files, artifact sources, and sidecars as described in the sections below.
  7. Expand Advanced to add config files, variables, and service hooks.
  8. Click Create.

Add a manifest​

Click + Add under Manifest and select a manifest type.

K8s manifest​

Use this type for standard Kubernetes YAML manifests, optionally rendered with Go templating and a values file.

FieldDescription
SourceThe location of your manifest files. Options include Harness Code, GitHub, GitLab, Bitbucket, Azure Repo, and Custom Remote.
IDA unique identifier for this manifest within the service.
RepositoryThe repository that contains your manifest files.
FetchSelect Branch to track a branch head, or Commit to pin to a specific SHA or Git tag.
Branch / CommitThe branch name or commit SHA to fetch.
File/Folder PathOne or more paths to manifest files or directories. If a path points to a directory, Harness fetches all .yaml files inside it.

Expand Advanced to add values files: one or more paths in the same repository that Harness merges into the manifest at render time. When multiple files are present, later files take priority over earlier ones.

Harness supports Go templating in K8s manifests. Use {{.Values.key}} syntax to reference values from your values files, and inject Harness expressions in values files only, not directly in manifests. For example, to reference the primary image:

  • CEL: ${{artifacts.primary.image}}
  • JEXL: <+artifacts.primary.image>

If your values file lives in a separate repository, add it as a standalone manifest of type Values YAML rather than attaching it under Advanced. A separate Values YAML manifest takes priority over any paths listed under Advanced and overwrites conflicting keys.

Example: rolling and canary deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello-app
  template:
    metadata:
      labels:
        app: hello-app
    spec:
      containers:
        - name: hello-app
          image: docker.io/hashicorp/http-echo:0.2.3
          args:
            - "-text=Hello from Harness CD"
          ports:
            - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
  name: hello-app
spec:
  type: ClusterIP
  selector:
    app: hello-app
  ports:
    - port: 80
      targetPort: 5678
Example: blue-green deployment

Blue-green deployments require two Services: one annotated as the primary and one as the stage. Harness uses these annotations to route traffic during the swap.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-app
spec:
  replicas: 2
  revisionHistoryLimit: 3
  selector:
    matchLabels:
      app: hello-app
  template:
    metadata:
      labels:
        app: hello-app
    spec:
      containers:
        - name: hello-app
          image: docker.io/hashicorp/http-echo:0.2.3
          args:
            - "-text=Hello from Harness CD"
          ports:
            - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
  name: hello-app
  annotations:
    harness.io/primary-service: "true"
spec:
  type: ClusterIP
  selector:
    app: hello-app
  ports:
    - port: 80
      targetPort: 5678
---
apiVersion: v1
kind: Service
metadata:
  name: hello-app-stage
  annotations:
    harness.io/stage-service: "true"
spec:
  type: ClusterIP
  selector:
    app: hello-app
  ports:
    - port: 80
      targetPort: 5678

Helm chart​

Use this type for a Helm chart stored in an HTTP Helm repository, OCI registry, Git repo, S3 bucket, or GCS bucket.

FieldDescription
SourceThe store type for your chart.
IDA unique identifier for this chart within the service.
Chart PathThe path to the chart folder from the root of the repository. For HTTP Helm and OCI sources, this is the chart name.
Helm VersionSelect V3.

Expand Advanced to add values override files. Harness merges these at render time. Later files take priority over earlier ones.

Kustomize​

Use this type for a Kustomize base with optional overlays stored in a Git repo or Harness File Store.

FieldDescription
SourceA Git provider, Harness File Store, or Azure Repo.
IDA unique identifier for this kustomization within the service.
Kustomize Folder PathThe path to the folder containing kustomization.yaml from the root of the repository.

Expand Advanced to add Kustomize patch files. Harness applies patches in the order listed. The last file wins on conflicting keys. You cannot use Harness expressions in the base manifest or kustomization.yaml. Add them to patch files only.

Harness does not use Kustomize for rollback. It renders templates with Kustomize, passes them to kubectl, and rollback works the same as native Kubernetes.

OpenShift template​

Use this type for an OpenShift template stored in a Git repo, Harness File Store, custom repo, or Azure Repo.

FieldDescription
SourceA Git provider, Harness File Store, custom repo, or Azure Repo.
IDA unique identifier for this template within the service.
Template File PathThe path to the template file from the root of the repository.

Expand Advanced to add OpenShift parameter files. You can also add parameters as a separate manifest of type OpenShift Param.

API version

Use apiVersion: apps.openshift.io/v1, not apiVersion: v1, in your OpenShift templates.

Add an additional override file​

Override files let you layer values on top of your base manifest at deploy time without modifying the manifest itself. This is useful for environment-specific configuration.

Click + Add under Additional override file. The fields match the manifest configuration: Type, Source, ID, Repository, Fetch, Branch, and File/Folder Path. When an override file is present, it takes priority over matching keys in the manifest's values files.

Add an artifact source​

Artifact sources define the container image that Harness injects at deploy time. Reference the primary artifact image in your values file:

  • CEL: ${{artifacts.primary.image}}
  • JEXL: <+artifacts.primary.image>

If you hardcode the image directly in your manifest, Harness ignores any artifact sources defined in the service.

Click + Add under Artifact source, select a type, and configure the connector and image details.

FieldDescription
ConnectorA Harness Docker Registry connector.
Image PathThe full image path, for example library/nginx or myorg/myapp. Wildcards are not supported.
TagThe image tag. Supports a fixed value, runtime input (<+input>), or a Harness expression.
DigestOptional. Pin the image to a specific digest or SHA value.

Add a sidecar​

Sidecar definitions specify images for containers that run alongside your main application container. Click + Add under Sidecar and configure an artifact source using the same registry types listed above.

Reference the sidecar image in your values file:

  • CEL: ${{artifacts.sidecars.<sidecar-id>.image}}
  • JEXL: <+artifacts.sidecars.<sidecar-id>.image>

Advanced service options​

Expand Advanced on the service to access options that apply across the entire service:

  • Config Files: Attach configuration files such as properties files, certificates, or scripts. Harness makes these available to the delegate at deploy time.
  • Variables: Define service-level variables to use in values files and pipeline expressions. Variables support fixed values, runtime inputs, and expressions. Reference them as:
    • CEL: ${{serviceVariables.<name>}}
    • JEXL: <+serviceVariables.<name>>
  • Service Hooks: Run scripts at specific points in the service lifecycle: before or after Harness fetches manifests or applies resources.

Use an existing service​

When you configure a stage, select Existing in the Choose service panel. Use the Project, Organization, and Account tabs to select from the appropriate scope. Only Kubernetes services appear when your stage deployment type is Kubernetes.

Next steps​

Last updated on