Skip to main content

CD artifact sources

In DevOps, an artifact source is a location where the compiled, tested, and ready-to-deploy software artifacts are stored. These artifacts could be container images, compiled binary files, executables, or any other software components that are part of the application.

To add an artifact source, you add a Harness connector to the artifact platform (DockerHub, GCR, Artifactory, etc.) and then add an artifact source to a Harness service that defines the artifact source name, path, tags, and so on.

This topic lists the artifact sources you can use in your Harness services.

Using artifacts in manifests

You have two options when referencing the artifacts you want to deploy:

  • Add an artifact source to the Harness service and reference it using the Harness expression <+artifacts.primary.image> in the values YAML file.
  • Hardcode the artifact into the manifests or values YAML file.

Use the artifact expression

Add the image location to Harness as an artifact in the Artifacts section of the service.

This allows you to reference the image in your values YAML files using the Harness expression <+artifacts.primary.image>.

...  
image: <+artifacts.primary.image>
...

You cannot use Harness variables expressions in your Kubernetes object manifest files. You can only use Harness variables expressions in values YAML files, or Kustomize Patch file.

When you select the artifact repo for the artifact, like a Docker Hub repo, you specify the artifact and tag/version to use.

You can select a specific tag/version, use a runtime input so that you are prompted for the tag/version when you run the pipeline, or you can use an Harness variable expression to pass in the tag/version at execution.

Here's an example where a runtime input is used and you select which image version/tag to deploy.

With a Harness artifact, you can template your manifests, detaching them from a hardcoded location. This makes your manifests reusable and dynamic.

Hardcode the artifact

If a Docker image location is hardcoded in your Kubernetes manifest (for example, image: nginx:1.14.2), then you can simply add the manifest to Harness in Manifests and Kubernetes will pull the image during deployment.

When you hardcode the artifact in your manifests, any artifacts added to your Harness service are ignored.

Docker

Use artifacts in any Docker registry

To use a Docker artifact, you create or use a Harness connector to connect to your Docker repo and then use that connector in your Harness service and reference the artifact to use.

Docker connector YAML
connector:
name: Docker Hub with Pwd
identifier: Docker_Hub_with_Pwd
description: ""
orgIdentifier: default
projectIdentifier: CD_Docs
type: DockerRegistry
spec:
dockerRegistryUrl: https://index.docker.io/v2/
providerType: DockerHub
auth:
type: UsernamePassword
spec:
username: johndoe
passwordRef: Docker_Hub_Pwd
executeOnDelegate: false
Service using Docker artifact YAML
service:
name: Example K8s2
identifier: Example_K8s2
serviceDefinition:
type: Kubernetes
spec:
manifests:
- manifest:
identifier: myapp
type: K8sManifest
spec:
store:
type: Harness
spec:
files:
- /Templates/deployment.yaml
valuesPaths:
- /values.yaml
skipResourceVersioning: false
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- spec:
connectorRef: Docker_Hub_with_Pwd
imagePath: library/nginx
tag: stable-perl
identifier: myimage
type: DockerRegistry
gitOpsEnabled: false

Important notes

  • For pulling Docker images from Docker repos, Harness is restricted by the limits of the Docker repo. For example, Docker Hub limits.
  • The maximum number of artifact image tags fetched by Harness that is 10000.

Docker artifact expressions

You can reference artifact properties using the following expressions in a values YAML file or in any Harness setting that supports Harness expressions.

ExpressionDescriptionExample
<+artifact.connectorRef>Identifier of the connector used by the artifact sourceorg.dockerhub
<+artifact.identifier>Identifier of the artifact source in the service definitionNGINX
<+artifact.type>This will be DockerRegistry alwaysDockerRegistry
<+artifact.primaryArtifact>Boolean values. true in case of primary artifacttrue
<+artifact.tag>This is the Docker tagv1
<+artifact.image>This is the image of the particular version. The value is used with docker pull commandindex.docker.io/library/nginx:v1
<+artifact.imagePath>This is the name of the image without registry info or tag.library/nginx
<+artifact.imagePullSecret>This will be the base64 encoded secret used for pulling the image
<+artifact.dockerConfigJsonSecret>This is the kubernetes.io/dockerconfigjson credentials
<+artifact.label.[PLACEHOLDER]>This is the label set in the Docker image. Replace the placeholder with the appropriate label
<+artifact.metadata.SHA>SHA of the Docker imagesha256:b3ebe55062b76860c6c0c78f5cae81ec393a944bcc96c05b5f411d3560c9f1d8
<+artifact.metadata.SHAV2>Docker supports v1 and v2 format. We list both the formats when applicable.sha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b

Google Container Registry (GCR)

Use GCR artifacts

You connect to GCR using a Harness GCP Connector. For details on all the GCR requirements for the GCP Connector, see Google Cloud Platform (GCP) Connector Settings Reference.

To use a GCR artifact, you create or use a Harness GCP Connector to connect to GCR repo and then use that connector in your Harness service and reference the artifact to use.

GCP connector YAML

This example uses a Harness Delegate installed in GCP for credentials.

connector:
name: GCR
identifier: GCR
description: ""
orgIdentifier: default
projectIdentifier: CD_Docs
type: Gcp
spec:
credential:
type: InheritFromDelegate
delegateSelectors:
- gcpdocplay
executeOnDelegate: true
Service using GCR artifact YAML
service:
name: Google Artifact
identifier: Google_Artifact
serviceDefinition:
type: Kubernetes
spec:
manifests:
- manifest:
identifier: manifests
type: K8sManifest
spec:
store:
type: Harness
spec:
files:
- account:/Templates
valuesPaths:
- account:/values.yaml
skipResourceVersioning: false
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- spec:
connectorRef: GCR
imagePath: docs-play/todolist-sample
tag: <+input>
registryHostname: gcr.io
identifier: myapp
type: Gcr
gitOpsEnabled: false

Permissions

For Google Container Registry (GCR), the following roles are required:

  • Storage Object Viewer (roles/storage.objectViewer)
  • Storage Object Admin (roles/storage.objectAdmin)

For more information, go to the GCP documentation about Cloud IAM roles for Cloud Storage.

Ensure the Harness Delegate you have installed can reach storage.cloud.google.com and your GCR registry host name, for example gcr.io.

Use Docker Registry for GCR

If you do not want to use the GCP connector for GCR, you can use the platform-agnostic Docker Registry connector.

Use the following settings:

  • Provider Type: select Other (Docker V2 compliant).
  • URL: Enter the GCR URL for your GCP account.
    • Example: https://gcr.io/my-account.
  • Authentication:
    • Username: Enter _token.
      • The usage of _token as a username for GCP authentication typically occurs when using certain command-line utilities or API clients that require an access token instead of a traditional username and password.
    • Password: Enter the output of the gcloud auth print-access-token command using a Harness secret.

Ensure that the GCP IAM user you use has the correct permissions for pulling from GCR.

Permissions

For Google Container Registry (GCR), the following roles are required:

  • Storage Object Viewer (roles/storage.objectViewer)
  • Storage Object Admin (roles/storage.objectAdmin)

For more information, go to the GCP documentation about Cloud IAM roles for Cloud Storage.

Ensure the Harness Delegate you have installed can reach storage.cloud.google.com and your GCR registry host name, for example gcr.io.

GCR artifact expressions

You can reference artifact properties using the following expressions in a values YAML file or in any Harness setting that supports Harness expressions.

ExpressionDescriptionExample
<+artifact.connectorRef>Identifier of the connector used by the artifact sourceorg.gcp
<+artifact.identifier>Identifier of the artifact source in the service definitionAcme_NGINX
<+artifact.type>This will be Gcr alwaysGcr
<+artifact.primaryArtifact>Boolean values. true in case of primary artifacttrue
<+artifact.tag>, <+artifact.metadata.tag>This is the Docker tagv1
<+artifact.image>, <+artifact.metadata.image>This is the image of the particular version. The value is used with docker pull commandus.gcr.io/cd-project/acme/nginx:v1
<+artifact.imagePath>This is the name of the image without registry info or tagcd-project/acme/nginx
<+artifact.imagePullSecret>This will be the base64 encoded secret used for pulling the image
<+artifact.dockerConfigJsonSecret>This is the kubernetes.io/dockerconfigjson credentials
<+artifact.registryHostname>GCR registry hostnameus.gcr.io
<+artifact.digest>This is the digest specified in the GCR artifact source definitionsha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.label.[PLACEHOLDER]>This is the label set in the Docker image. Replace the placeholder with the appropriate label
<+artifact.metadata.SHAV2>Docker supports v1 and v2 format. We list both the formats when applicable.sha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.metadata.SHA>SHA of the Docker imagesha256:b3ebe55062b76860c6c0c78f5cae81ec393a944bcc96c05b5f411d3560c9f1d8

Google Cloud Storage (GCS)

Use GCS artifacts

You connect to GCS using a Harness GCP Connector. For details on all the GCS requirements for the GCP Connector, see Google Cloud Platform (GCP) Connector Settings Reference.

To use a GCS artifact, you create or use a Harness GCP Connector to connect to GCS bucket and then use that connector in your Harness service and reference the artifact to use.

GCP connector YAML

This example uses a Harness Delegate installed in GCP for credentials.

connector:
name: GCS
identifier: GCS
description: ""
orgIdentifier: default
projectIdentifier: CD_Docs
type:
spec:
credential:
type: InheritFromDelegate
delegateSelectors:
- gcpdocplay
executeOnDelegate: true
Service using GCS artifact YAML
service:
name: GCS
identifier: GCS
tags: {}
serviceDefinition:
spec:
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- spec:
connectorRef: GCP_Connector
project: myapp
bucket: functions
artifactPath: myfunction.zip
identifier: myfunction
type: GoogleCloudStorage
manifests:
- manifest:
identifier: myfunction
type: GoogleCloudFunctionDefinition
spec:
store:
type: Harness
spec:
files:
- /google-cloud-function/myfunction
type: GoogleCloudFunctions

Permissions

For Google Cloud Storage (GCS), the following roles are required:

  • Storage Object Viewer (roles/storage.objectViewer)
  • Storage Object Admin (roles/storage.objectAdmin)

For more information, go to the GCP documentation about Cloud IAM roles for Cloud Storage.

GCS artifact expressions

You can reference artifact properties using the following expressions in a values YAML file or in any Harness setting that supports Harness expressions.

ExpressionDescriptionExample
<+artifact.connectorRef>Identifier of the connector used by the artifact sourceorg.gcp
<+artifact.identifier>Identifier of the artifact source in the service definitionAcmeGcs
<+artifact.type>This will be GoogleCloudStorage alwaysGoogleCloudStorage
<+artifact.primaryArtifact>Boolean values. true in case of primary artifacttrue
<+artifact.artifactPath>, <+artifact.metadata.artifactName>Full Path of the file in GCS bucketacme-apps/hello-world/v1.tgz
<+artifact.bucket>, <+artifact.metadata.bucket>GCS bucketacme-lambda
<+artifact.url>URL to the artifact filehttps://www.googleapis.com/storage/v1/b/acme-lambda/acme-apps/hello-world/v1.tgz
<+artifact.project>GCP projectacme-devs

Google Artifact Registry

Use Google Artifact Registry artifacts

You connect to Google Artifact Registry using a Harness GCP Connector.

For details on all the Google Artifact Registry requirements for the GCP Connector, see Google Cloud Platform (GCP) Connector Settings Reference.

This example uses a Harness Delegate installed in GCP for credentials.

Google Artifact Registry connector YAML
connector:
name: Google Artifact Registry
identifier: Google_Artifact_Registry
description: ""
orgIdentifier: default
projectIdentifier: CD_Docs
type: Gcp
spec:
credential:
type: InheritFromDelegate
delegateSelectors:
- gcpdocplay
executeOnDelegate: true
Service using Google Artifact Registry artifact YAML
service:
name: Google Artifact Registry
identifier: Google_Artifact_Registry
tags: {}
serviceDefinition:
spec:
manifests:
- manifest:
identifier: myapp
type: K8sManifest
spec:
store:
type: Harness
spec:
files:
- /Templates
valuesPaths:
- /values.yaml
skipResourceVersioning: false
enableDeclarativeRollback: false
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- identifier: myapp
spec:
connectorRef: Google_Artifact_Registry
repositoryType: docker
project: docs-play
region: us-central1
repositoryName: quickstart-docker-repo
package: quickstart-docker-repo
version: <+input>
type: GoogleArtifactRegistry
type: Kubernetes

Permissions

For Google Artifact Registry, the following roles are required:

  • Artifact Registry Reader
  • Artifact Registry Writer

For more information, go to the GCP documentation Configure roles and permissions.

Ensure the Harness Delegate you have installed can reach your Google Artifact Registry region, for example us-central1.

Google Artifact Registry artifact expressions

You can reference artifact properties using the following expressions in a values YAML file or in any Harness setting that supports Harness expressions.

ExpressionDescriptionExample
<+artifact.connectorRef>Identifier of the connector used by the artifact sourceorg.gcp
<+artifact.identifier>Identifier of the artifact source in the service definitionAcmeGAR
<+artifact.type>This will be GoogleArtifactRegistry alwaysGoogleArtifactRegistry
<+artifact.primaryArtifact>Boolean values. true in case of primary artifacttrue
<+artifact.version>This is the Docker tagv1
<+artifact.region>Region where the GAR repository is hostedus
<+artifact.pkg>Name of the GAR packagealpine
<+artifact.repositoryType>Type of repository.docker
<+artifact.image>, <+artifact.metadata.image>This is the image of the particular version. The value is used with `docker pull` commandus-docker.pkg.dev/acme-dev/acme-docker/alpine:v1
<+artifact.repositoryName>Name of the repository in GARacme-docker
<+artifact.project>Project ID in GCPacme-dev
<+artifact.registryHostname>, <+artifact.metadata.registryHostname>This is the hostname of the registryus-docker.pkg.dev
<+artifact.imagePullSecret>This will be the base64 encoded secret used for pulling the image
<+artifact.dockerConfigJsonSecret>This is the kubernetes.io/dockerconfigjson credentials. Valid for docker only
<+artifact.digest>This is the digest specified in the ECR artifact source definition. Valid for docker onlysha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.label.[PLACEHOLDER]>This is the label set in the Docker image. Replace the placeholder with the appropriate label. Valid for docker only
<+artifact.metadata.SHAV2>Docker supports v1 and v2 format. We list both the formats when applicable. Valid for docker onlysha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.metadata.SHA>SHA of the Docker image. Valid for docker onlysha256:b3ebe55062b76860c6c0c78f5cae81ec393a944bcc96c05b5f411d3560c9f1d8

Azure DevOps Artifacts

Use Azure Artifacts

You connect to your Azure DevOps artifacts using a Harness Azure Artifacts connector.

Azure Artifacts connector YAML
connector:
name: Azure Artifacts
identifier: Azure_Artifacts
description: ""
orgIdentifier: default
projectIdentifier: CD_Docs
type: AzureArtifacts
spec:
azureArtifactsUrl: https://dev.azure.com/garvit-test
auth:
spec:
type: PersonalAccessToken
spec:
tokenRef: azureartifactspat
delegateSelectors:
- gcpdocplay
executeOnDelegate: true
Service using Azure Artifacts artifact YAML
service:
name: Azure Artifacts
identifier: Azure_Artifacts
tags: {}
serviceDefinition:
spec:
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- identifier: mypackage
spec:
connectorRef: Azure_Artifacts
scope: org
feed: garvit-test
packageType: maven
package: com.mycompany.app:my-app
version: 1.1-SNAPSHOT
type: AzureArtifacts
type: Ssh

Deployment type support

Azure DevOps Artifacts are can be used with the following Harness deployment types:

  • SSH
  • WinRM
  • Azure Web Apps
  • Tanzu

Package type support

Harness supports Maven and Nuget package types.

Harness also supports universal packages, which enable developers to store an extensive array of package types that extend beyond the conventional ones. Note the following:

  • Currently support is limited to traditional VM deployments using SSH or WinRM.

  • Artifact source templates are not currently supported for universal packages.

Here's an example definition of a universal package in a Harness service definition:

service:
name: azure
identifier: azure
tags: {}
serviceDefinition:
spec:
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- identifier: azure
spec:
connectorRef: azure
scope: org
feed: universaltest68137
packageType: upack
package: my-first-package
version: 0.0.1
type: AzureArtifacts
type: AzureWebApp

Azure DevOps URL

This is the URL in your browser when you are in the Azure DevOps organization containing the projects and feed(s) you want to use.

For example, in this URL, https://dev.azure.com/garvit-test/sample-project/_packaging?_a=feed&feed=other-feed, you only need to use https://dev.azure.com/garvit-test in Harness connector Azure DevOps URL setting.

Permissions

You use an Azure DevOps Personal Access Token (PAT) to authenticate with Azure.

Create a Personal Access token as described in Authenticate access with personal access tokens from Azure.

Next, copy the token and paste it in the Harness Encrypted Text secret you use for the PAT in the Harness Azure Artifacts connector.

The PAT must have the Read permission in Packaging.

Azure DevOps artifacts expressions

You can reference artifact properties using the following expressions in a values YAML file or in any Harness setting that supports Harness expressions.

ExpressionDescriptionExample
<+artifact.connectorRef>Identifier of the connector used by the artifact sourceorg.azuredevops
<+artifact.identifier>Identifier of the artifact source in the service definitionAcmeAzureDevops
<+artifact.type>This will be AzureArtifacts alwaysAzureArtifacts
<+artifact.primaryArtifact>Boolean values. true in case of primary artifacttrue
<+artifact.project>Name of the projects in Azure Artifactsacme-project
<+artifact.feed>Name of the feed in Azure artifactsacme-feed-universal
<+artifact.scope>It will be one of org or projectproject
<+artifact.packageType>Package type. It is one of upack, mavenupack
<+artifact.packageName>Name of the package in the feedacme-upacks
<+artifact.version>Version of the artifact0.0.1
<+artifact.metadata.get([KEY])>This is the metadata attached with the file in Azure Devops. Popular keys include publishDate, versionId, version.

Azure Container Registry (ACR)

Use ACR artifacts

You connect to ACR using a Harness Azure Connector. For details on all the Azure requirements for the Azure Connector, see Add a Microsoft Azure cloud connector.

This example uses a Harness Delegate installed in Azure for credentials.

Azure connector for ACR YAML
connector:
name: ACR-docs
identifier: ACRdocs
description: ""
orgIdentifier: default
projectIdentifier: CD_Docs
type: Azure
spec:
credential:
type: ManualConfig
spec:
applicationId: xxxxx-xxxx-xxxx-xxxx-xxxxx
tenantId: xxxxx-xxxx-xxxx-xxxx-xxxxx
auth:
type: Secret
spec:
secretRef: acrvalue
azureEnvironmentType: AZURE
executeOnDelegate: false
Service using ACR artifact YAML
service:
name: Azure with ACR
identifier: Azure
tags: {}
serviceDefinition:
spec:
manifests:
- manifest:
identifier: myapp
type: K8sManifest
spec:
store:
type: Harness
spec:
files:
- /Templates
valuesPaths:
- /values.yaml
skipResourceVersioning: false
enableDeclarativeRollback: false
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- spec:
connectorRef: ACRdocs
tag: <+input>
subscriptionId: <+input>
registry: <+input>
repository: <+input>
identifier: myapp
type: Acr
type: Kubernetes

Permissions

The Harness Azure connectors that you'll use to connect Harness to ACR must have the Reader role, at minimum. You can also use a custom role that includes the permissions of the Reader role.

Reader role information

ACR Reader role

The Reader role must be assigned at the Subscription or Resource Group level that is used by the Application (Client) Id that you'll use in the Azure connector's settings. The application must have permission to list all container registries.

tip

Make sure you:

  • Don't put the Reader role in a different IAM section of Azure.
  • Don't provide only the AcrPull role, instead of Reader. It might appear that the AcrPull role gives access to a specific registry, but Harness needs to list all registries.
Custom role information

The following permissions (actions) are necessary for any Service Principal and/or Managed Identity user, regardless of whether you are using Kubernetes RBAC or Azure RBAC:

  • Microsoft.ContainerRegistry/registries/read
  • Microsoft.ContainerRegistry/registries/builds/read
  • Microsoft.ContainerRegistry/registries/metadata/read
  • Microsoft.ContainerRegistry/registries/pull/read
  • Microsoft.ContainerService/managedClusters/read
  • Microsoft.ContainerService/managedClusters/listClusterUserCredential/action
  • Microsoft.Resource/subscriptions/resourceGroup/read

For Helm deployments, the version of Helm must be >= 3.2.0. The Harness HELM_VERSION_3_8_0 feature flag must be activated.

You can't use Pod Assigned Managed Identity and System Assigned Managed Identity for the same cluster.

The following JSON sample creates a custom role with the required permissions. To use this sample, replace xxxx with the role name, subscription Id, and resource group Id.

{
"id": "/subscriptions/xxxx/providers/Microsoft.Authorization/roleDefinitions/xxxx",
"properties": {
"roleName": "xxxx",
"description": "",
"assignableScopes": [
"/subscriptions/xxxx/resourceGroups/xxxx"
],
"permissions": [
{
"actions": [],
"notActions": [],
"dataActions": [
"Microsoft.ContainerService/managedClusters/configmaps/read",
"Microsoft.ContainerService/managedClusters/configmaps/write",
"Microsoft.ContainerService/managedClusters/configmaps/delete",
"Microsoft.ContainerService/managedClusters/secrets/read",
"Microsoft.ContainerService/managedClusters/secrets/write",
"Microsoft.ContainerService/managedClusters/secrets/delete",
"Microsoft.ContainerService/managedClusters/apps/deployments/read",
"Microsoft.ContainerService/managedClusters/apps/deployments/write",
"Microsoft.ContainerService/managedClusters/apps/deployments/delete",
"Microsoft.ContainerService/managedClusters/events/read",
"Microsoft.ContainerService/managedClusters/events/write",
"Microsoft.ContainerService/managedClusters/events/delete",
"Microsoft.ContainerService/managedClusters/namespaces/read",
"Microsoft.ContainerService/managedClusters/nodes/read",
"Microsoft.ContainerService/managedClusters/pods/read",
"Microsoft.ContainerService/managedClusters/pods/write",
"Microsoft.ContainerService/managedClusters/pods/delete",
"Microsoft.ContainerService/managedClusters/services/read",
"Microsoft.ContainerService/managedClusters/services/write",
"Microsoft.ContainerService/managedClusters/services/delete",
"Microsoft.ContainerService/managedClusters/apps/statefulsets/read",
"Microsoft.ContainerService/managedClusters/apps/statefulsets/write",
"Microsoft.ContainerService/managedClusters/apps/statefulsets/delete",
"Microsoft.ContainerService/managedClusters/apps/replicasets/read",
"Microsoft.ContainerService/managedClusters/apps/replicasets/write",
"Microsoft.ContainerService/managedClusters/apps/replicasets/delete"
],
"notDataActions": []
}
]
}
}

Important notes

  • Harness supports 500 images from an ACR repo. If you don't see some of your images, then you might have exceeded this limit. This is the result of an Azure API limitation.
  • If you connect to an ACR repo via the platform-agnostic Docker Connector, the limit is 100.
Use Docker Registry connector for ACR

If you do not want to centrally manage service principles for access to ACR, you can use the platform-agnostic Docker Registry connector and repository-scoped permissions to connect Harness to ACR.

To use the Docker Registry connector to connect to ACR, do the following:

  1. In Azure ACR, in Repository permissions, select Tokens.
  1. Create a new token and scope map.
  1. Generate the password for the token.
  1. In Harness, create a new Docker Registry connector.
  2. For Provider Type, select Other.
  3. Select Username and Password for Authentication, and use the username and password for the ACR token.

ACR artifact expressions

You can reference artifact properties using the following expressions in a values YAML file or in any Harness setting that supports Harness expressions.

ExpressionDescriptionExample
<+artifact.connectorRef>Identifier of the connector used by the artifact sourceorg.azureConnector
<+artifact.identifier>Identifier of the artifact source in the service definitionAcmeAcrRegistry
<+artifact.type>This will be Acr alwaysAcr
<+artifact.primaryArtifact>Boolean values. true in case of primary artifacttrue
<+artifact.subscription>This is the Azure cloud subscription ID20d6a917-99fa-4b1b-9b2e-a3d624e9dcf0
<+artifact.registry>, <+artifact.metadata.registryHostname>Container registry hostnameacme.azurecr.io
<+artifact.tag>, <+artifact.metadata.tag>This is the Docker tagv1
<+artifact.image>, <+artifact.metadata.image>This is the image of the particular version. The value is used with `docker pull` commandacme.azurecr.io/hello-world:v1
<+artifact.repository>This is the name of the image without registry info or taghello-world
<+artifact.imagePullSecret>This will be the base64 encoded secret used for pulling the image
<+artifact.dockerConfigJsonSecret>This is the kubernetes.io/dockerconfigjson credentials
<+artifact.digest>This is the digest specified in the ACR artifact source definitionsha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.label.[PLACEHOLDER]>This is the label set in the Docker image. Replace the placeholder with the appropriate label
<+artifact.metadata.SHAV2>Docker tends to support v1 and v2 format. We list both formats when applicable.sha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.metadata.SHA>SHA of the Docker imagesha256:b3ebe55062b76860c6c0c78f5cae81ec393a944bcc96c05b5f411d3560c9f1d8

Amazon Elastic Container Registry (ECR)

Use ECR artifacts

You connect to ECR using a Harness AWS connector. For details on all the ECR requirements for the AWS connector, see AWS Connector Settings Reference.

This example uses a Harness Delegate installed in AWS for credentials.

ECR connector YAML
connector:
name: ECR
identifier: ECR
orgIdentifier: default
projectIdentifier: CD_Docs
type: Aws
spec:
credential:
type: ManualConfig
spec:
accessKey: xxxxx
secretKeyRef: secretaccesskey
region: us-east-1
delegateSelectors:
- doc-immut
executeOnDelegate: true
Service using ECR artifact YAML
service:
name: ECR
identifier: ECR
tags: {}
serviceDefinition:
spec:
manifests:
- manifest:
identifier: myapp
type: K8sManifest
spec:
store:
type: Harness
spec:
files:
- /values.yaml
valuesPaths:
- /Templates
skipResourceVersioning: false
enableDeclarativeRollback: false
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- spec:
connectorRef: ECR
imagePath: todolist-sample
tag: "1.0"
region: us-east-1
identifier: myapp
type: Ecr
type: Kubernetes

Permissions

Ensure that the AWS IAM user account you use in the AWS Connector has the following policy.

Pull from ECR policy
  • Policy Name: AmazonEC2ContainerRegistryReadOnly
  • Policy ARN: arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly
  • Description: Provides read-only access to Amazon EC2 Container Registry repositories.
  • Policy JSON:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:GetAuthorizationToken",
"ecr:BatchCheckLayerAvailability",
"ecr:GetDownloadUrlForLayer",
"ecr:GetRepositoryPolicy",
"ecr:DescribeRepositories",
"ecr:ListImages",
"ecr:DescribeImages",
"ecr:BatchGetImage"
],
"Resource": "*"
}
]
}
Use Docker Registry for ECR

If you do not want to use the AWS connector for ECR, you can use the platform-agnostic Docker Registry connector.

Use the following settings:

  • Provider Type: select Other (Docker V2 compliant).
  • URL: Enter the same URL you would use in your push command.
    • For example, here is an ECR push command example:

      docker push 1234567890.dkr.ecr.us-east-2.amazonaws.com/my-private-repo:123.

    • Include the https:// scheme when you add the URL in URL.

    • Your URL will look something like this: https://1234567890.dkr.ecr.us-east-2.amazonaws.com.

  • Authentication:
    • Username: Enter AWS. Do not enter an access key or user name.

    • Password: Enter the password returned from the following command (replace us-east-2 with your region):

      aws ecr get-login-password --region us-east-2

Ensure that the AWS IAM user you use has the correct policies for pulling from ECR:

Pull from ECR policy
  • Policy Name: AmazonEC2ContainerRegistryReadOnly
  • Policy ARN: arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly
  • Description: Provides read-only access to Amazon EC2 Container Registry repositories.
  • Policy JSON:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:GetAuthorizationToken",
"ecr:BatchCheckLayerAvailability",
"ecr:GetDownloadUrlForLayer",
"ecr:GetRepositoryPolicy",
"ecr:DescribeRepositories",
"ecr:ListImages",
"ecr:DescribeImages",
"ecr:BatchGetImage"
],
"Resource": "*"
}
]
}
AWS roles for IRSA auth

If you are using IRSA for authentication in the Harness AWS connector that pulls from ECR, ensure the following AWS roles are mapped to the Kubernetes service account.

  • ecr:DescribeImages
  • ecr:DescribeRepository
  • ecr:GetAuthorizationToken
  • ecr:BatchGetImage
  • ecr:GetDownloadUrlForLayer

ECR artifact expressions

You can reference artifact properties using the following expressions in a values YAML file or in any Harness setting that supports Harness expressions.

ExpressionDescriptionExample
<+artifact.connectorRef>Identifier of the connector used by the artifact sourceorg.aws
<+artifact.identifier>Identifier of the artifact source in the service definitionAcmeEcr
<+artifact.type>This will be Ecr alwaysEcr
<+artifact.primaryArtifact>Boolean values. true in case of primary artifacttrue
<+artifact.registryId>Registry ID of the ECR registry as set in the artifact source config.4793702123451
<+artifact.tag>, <+artifact.metadata.tag>This is the Docker tagv1
<+artifact.image>, <+artifact.metadata.image>This is the image of the particular version. The value is used with `docker pull` commandus-east-1.ecr.io/hello-world:v1
<+artifact.imagePath>This is the name of the image without registry info or taghello-world
<+artifact.imagePullSecret>This will be the base64 encoded secret used for pulling the image
<+artifact.dockerConfigJsonSecret>This is the kubernetes.io/dockerconfigjson credentials
<+artifact.digest>This is the digest specified in the ECR artifact source definitionsha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.label.[PLACEHOLDER]>This is the label set in the Docker image. Replace the placeholder with the appropriate label
<+artifact.metadata.SHAV2>Docker supports v1 and v2 format. We list both formats when applicable.sha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.metadata.SHA>SHA of the Docker imagesha256:b3ebe55062b76860c6c0c78f5cae81ec393a944bcc96c05b5f411d3560c9f1d8

Amazon S3 Cloud Storage

Use AWS artifacts

You connect to AWS using a Harness AWS connector. For details on all the AWS requirements for the connector, see AWS Connector Settings Reference.

This example uses a Harness Delegate installed in AWS for credentials.

AWS connector YAML
connector:
name: jsmith-aws
identifier: jsmithaws
description: ""
orgIdentifier: default
projectIdentifier: jsmith_project
type: Aws
spec:
credential:
type: ManualConfig
spec:
accessKeyRef: jsmithawsaccesskeyid
secretKeyRef: jsmithawssecretaccesskey
region: us-east-1
executeOnDelegate: false
Service using S3 artifact YAML
service:
name: jsmith-aws-s3-test
identifier: jsmithawss3test
tags: {}
serviceDefinition:
spec:
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- spec:
connectorRef: jsmithaws
bucketName: jsmith-bucket
filePath: login-service.sh
identifier: jsmith_login_service_test_sh
type: AmazonS3
type: Ssh

Permissions

You need a dedicated S3 bucket for your artifacts and an AWS connector with read/write access to this bucket.

Sample S3 Cache Bucket Policy
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowS3BucketAccess",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:ListBucket",
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::your-s3-bucket/*",
"arn:aws:s3:::your-s3-bucket"
]
},
{
"Sid": "AllowDescribeRegions",
"Effect": "Allow",
"Action": "ec2:DescribeRegions",
"Resource": "*"
}
]
}

For more information on configuring an S3 connector and S3 bucket policies, go to Add an AWS connector and the AWS connector settings reference.

AWS S3 artifact expressions

You can reference artifact properties using the following expressions in a values YAML file or in any Harness setting that supports Harness expressions.

ExpressionDescriptionExample
<+artifact.connectorRef>Identifier of the connector used by the artifact sourceorg.aws
<+artifact.identifier>Identifier of the artifact source in the service definitionAcmeS3
<+artifact.type>This will be AmazonS3 alwaysAmazonS3
<+artifact.primaryArtifact>Boolean values. true in case of primary artifacttrue
<+artifact.filePath>Full path of the file in S3 bucketacme-apps/hello-world/v1.tgz
<+artifact.region>Region of S3 bucketus-east-1
<+artifact.bucketName>Name of the S3 bucketacme-lambda
<+artifact.metadata.get([KEY])>This is the metadata attached with the file in AWS S3. Popular keys include x-amz-server-side-encryption, Content-Type, Last-Modified.

AWS S3 File Filter

The artifact details settings include a File Filter (fileFilter) option.

In File Filter, you can enter a regex value and Harness will fetch all matching files. You can then select from the list in File Path.

This setting is optional. If you do not use it, Harness will fetch and display all files in the File Path setting.

If the File Path is a fixed value, during pipeline execution, artifact validation is performed using the File Path but not the File Filter. Harness does not check whether the File Filter matches or not during the execution.

Examples:

  • *: fetch all files in the file path.
  • *.zip: fetch all files in the file path with the extension .zip.
  • */w10/*.tfstate: fetch all files in the file path that contain /w10/ with the extension .tfstate.
  • */w1/*: fetch all files in the file path that contain /w1/.
  • w1: fetch all files in the file path that contain w1.

Amazon EC2 AMIs

Use Amazon EC2 AMI artifacts

You connect to Amazon AWS account using a Harness AWS connector. For details on all the AWS requirements for the connector, see AWS Connector Settings Reference.

For AWS AMI artifacts, a version number represents the name of AMI. You can filter names by using tags/filter values.

This example uses a Harness Delegate installed in AWS for credentials.

AWS connector YAML
connector:
name: jsmith-aws
identifier: jsmithaws
description: ""
orgIdentifier: default
projectIdentifier: jsmith_project
type: Aws
spec:
credential:
type: ManualConfig
spec:
accessKeyRef: jsmithawsaccesskeyid
secretKeyRef: jsmithawssecretaccesskey
region: us-east-1
executeOnDelegate: false
Service using EC2 AMI YAML

service:
name: jsmith-delegate-ami-test
identifier: jsmithdelegateamitest
tags: {}
serviceDefinition:
spec:
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- identifier: macos_build_farm_for_ci
spec:
connectorRef: jsmithaws
region: us-east-1
tags:
- name: Version
value: ""
filters:
- name: ami-image-id
value: ami-xxxxxxxxxxxxxxxxx
version: macos-build-farm-for-ci
type: AmazonMachineImage
type: Asg

Nexus

Use Nexus artifacts

You connect to Nexus using a Harness Nexus Connector. For details on all the requirements for the Nexus Connector, see Nexus Connector Settings Reference.

Nexus connector YAML
connector:
name: Harness Nexus
identifier: Harness_Nexus
description: ""
orgIdentifier: default
projectIdentifier: CD_Docs
type: HttpHelmRepo
spec:
helmRepoUrl: https://nexus3.dev.harness.io/repository/test-helm/
auth:
type: UsernamePassword
spec:
username: harnessadmin
passwordRef: nexus3pwd
delegateSelectors:
- gcpdocplay
Service using Nexus artifact YAML
service:
name: Nexus Example
identifier: Nexus_Example
tags: {}
serviceDefinition:
spec:
manifests:
- manifest:
identifier: myapp
type: K8sManifest
spec:
store:
type: Harness
spec:
files:
- /Templates
valuesPaths:
- /values.yaml
skipResourceVersioning: false
enableDeclarativeRollback: false
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- spec:
connectorRef: account.Harness_Nexus
repository: todolist
repositoryFormat: docker
tag: "4.0"
spec:
artifactPath: nginx
repositoryPort: "6661"
identifier: myapp
type: Nexus3Registry
type: Kubernetes

Permissions

Ensure the connected user account has the following permissions in the Nexus Server.

  • Repo: All repositories (Read)
  • Nexus UI: Repository Browser

Nexus repo perms for Harness

See Nexus Managing Security.

For Nexus 3, when used as a Docker repo, the user needs:

  • A role with the nx-repository-view-*_*_* privilege.

Nexus3 artifact expressions

You can reference artifact properties using the following expressions in a values YAML file or in any Harness setting that supports Harness expressions.

ExpressionDescriptionExample
<+artifact.connectorRef>Identifier of the connector used by the artifact sourceorg.nexus
<+artifact.identifier>Identifier of the artifact source in the service definitionAcmeNexus3
<+artifact.type>This will be Nexus3Registry alwaysNexus3Registry
<+artifact.primaryArtifact>Boolean values. true in case of primary artifacttrue
<+artifact.tag>, <+artifact.metadata.tag>This is the Docker tagv1
<+artifact.repositoryFormat>Type of repository. It is one of docker, maven, nuget, npm, rawdocker
<+artifact.image>, <+artifact.metadata.image>This is the image of the particular version. The value is used with `docker pull` commandnexus3.acme.io:80/nginx:v1.0
<+artifact.repositoryName>Name of the repository in Nexus3acme-docker
<+artifact.artifactPath>This is the name of the image without registry info or tagnginx
<+artifact.registryHostname>, <+artifact.metadata.registryHostname>This is the hostname of the registrynexus3.acme.io
<+artifact.imagePullSecret>This will be the base64 encoded secret used for pulling the image
<+artifact.dockerConfigJsonSecret>This is the kubernetes.io/dockerconfigjson credentials. Valid for docker only
<+artifact.digest>This is the digest specified in the ECR artifact source definition. Valid for docker onlysha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.label.[PLACEHOLDER]>This is the label set in the Docker image. Replace the placeholder with the appropriate label. Valid for docker only
<+artifact.metadata.SHAV2>Docker supports v1 and v2 format. We list both the formats when applicable. Valid for docker onlysha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.metadata.SHA>SHA of the Docker image. Valid for docker onlysha256:b3ebe55062b76860c6c0c78f5cae81ec393a944bcc96c05b5f411d3560c9f1d8
<+artifact.metadata.groupId>GroupId of the maven artifact. Valid for maven onlymygroup
<+artifact.metadata.artifactId>ArtifactId of the maven artifact. Valid for maven onlymyartifact
<+artifact.metadata.repositoryName>Name of the repository in Nexus3. Valid for everything except docker onlymaven-releases
<+artifact.metadata.version>Valid for everything except docker only1.2
<+artifact.metadata.url>URL of the file. Valid for everything except docker onlyhttps://nexus3.acme.io/repository/maven-releases/mygroup/myartifact/1.2/myartifact-1.2.war
<+artifact.metadata.filename>Name of the file. Valid for everything except docker onlymyartifact-1.2.war
<+artifact.metadata.imagePath>Path of the file. Valid for everything except docker onlymygroup/myartifact/1.2/myartifact-1.2.war

Nexus2 artifact expressions

You can reference artifact properties using the following expressions in a values YAML file or in any Harness setting that supports Harness expressions.

ExpressionDescriptionExample
<+artifact.connectorRef>Identifier of the connector used by the artifact sourceorg.nexus
<+artifact.identifier>Identifier of the artifact source in the service definitionAcmeNexus2
<+artifact.type>This will be Nexus2Registry alwaysNexus2Registry
<+artifact.primaryArtifact>Boolean values. true in case of primary artifacttrue
<+artifact.tag>, <+artifact.metadata.version>This is the version of the nexus artifactv1
<+artifact.repositoryFormat>Type of repository. It is one of maven, nuget, npmmaven
<+artifact.repositoryName>Name of the repository in Nexus2acme-mvn
<+artifact.artifactPath>This is the artifactIdmyartifact
<+artifact.imagePullSecret>This will be the base64 encoded secret used for pulling the file
<+artifact.metadata.groupId>GroupId of the maven artifact. Valid for maven onlymygroup
<+artifact.metadata.artifactId>ArtifactId of the maven artifact. Valid for maven onlymyartifact
<+artifact.metadata.repositoryName>Name of the repository in Nexus2.maven-releases
<+artifact.metadata.url>URL of the file.https://nexus2.acme.io/service/local/artifact/maven/content?r=maven-releases&g=mygroup&a=myartifact&v=1.0&p=jar&e=jar&c=testbundle
<+artifact.metadata.filename>Name of the file.foo-1.0-testbundle.jar

Artifactory

Use Artifactory artifacts

You connect to Artifactory (JFrog) using a Harness Artifactory Connector. For details on all the requirements for the Artifactory Connector, see Artifactory Connector Settings Reference.

Artifactory connector YAML
connector:
name: artifactory-tutorial-connector
identifier: artifactorytutorialconnector
orgIdentifier: default
projectIdentifier: CD_Docs
type: Artifactory
spec:
artifactoryServerUrl: https://harness.jfrog.io/artifactory/
auth:
type: Anonymous
executeOnDelegate: false
Service using Artifactory artifact YAML
service:
name: Artifactory Example
identifier: Artifactory_Example
tags: {}
serviceDefinition:
spec:
manifests:
- manifest:
identifier: myapp
type: K8sManifest
spec:
store:
type: Harness
spec:
files:
- /Templates
valuesPaths:
- /values.yaml
skipResourceVersioning: false
enableDeclarativeRollback: false
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- spec:
connectorRef: artifactorytutorialconnector
artifactPath: alpine
tag: 3.14.2
digest: sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
repository: bintray-docker-remote
repositoryUrl: harness-docker.jfrog.io
repositoryFormat: docker
identifier: myapp
type: ArtifactoryRegistry
type: Kubernetes

Permissions

Make sure the following permissions are granted to the user:

  • Privileged User is required to access API, whether Anonymous or a specific username (username and passwords are not mandatory).
  • Read permission to all Repositories.

If used as a Docker Repo, user needs:

  • List images and tags
  • Pull images

See Managing Permissions: JFrog Artifactory User Guide.

Artifactory artifact expressions

You can reference artifact properties using the following expressions in a values YAML file or in any Harness setting that supports Harness expressions.

ExpressionDescriptionExample
<+artifact.connectorRef>Identifier of the connector used by the artifact sourceorg.artifactory
<+artifact.identifier>Identifier of the artifact source in the service definitionAcmeArtifactory
<+artifact.type>This will be ArtifactoryRegistry alwaysArtifactoryRegistry
<+artifact.primaryArtifact>Boolean values. true in case of primary artifacttrue
<+artifact.tag>, <+artifact.metadata.tag>This is the Docker tagv1
<+artifact.repositoryFormat>Type of repository. It is one of docker, genericdocker
<+artifact.image>, <+artifact.metadata.image>This is the image of the particular version. The value is used with `docker pull` commandacme.jfrog.io/todolist-app/nginx:v1
<+artifact.repositoryName>Name of the repository in Artifactorytodolist-app
<+artifact.imagePath>, <+artifact.artifactPath>This is the name of the image without registry info or tagnginx
<+artifact.artifactDirectory>Path to the directory of where the generic artifacts are stored. As specified in the artifact source config. Valid for generic only./acme/dev/app
<+artifact.registryHostname>, <+artifact.metadata.registryHostname>This is the hostname of the registryacme.jfrog.io
<+artifact.imagePullSecret>This will be the base64 encoded secret used for pulling the image
<+artifact.dockerConfigJsonSecret>This is the kubernetes.io/dockerconfigjson credentials. Valid for docker only.
<+artifact.digest>This is the digest specified in the Artifactory artifact source definition. Valid for docker onlysha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.label.[PLACEHOLDER]>This is the label set in the Docker image. Replace the placeholder with the appropriate label. Valid for docker only
<+artifact.metadata.SHAV2>Docker tends to support v1 and v2 format. We list both formats when applicable. Valid for docker onlysha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.metadata.SHA>SHA of the Docker image. Valid for docker onlysha256:b3ebe55062b76860c6c0c78f5cae81ec393a944bcc96c05b5f411d3560c9f1d8
<+artifact.metadata.filename>Name of the file. Valid for generic only.artifact.zip
<+artifact.metadata.url>URL to the file. Valid for generic only.https://acme.jfrog.io/artifactory/todolist/artifact.zip

Bamboo

note

Currently, Bamboo support is behind the feature flag BAMBOO_ARTIFACT_NG. Contact Harness Support to enable the feature.

Use Bamboo build plans as artifacts

You can use Bamboo for build plans when performing deployments using the SSH/WinRM, Serverless.com Framework, and Deployment Templates deployment types. You can also trigger deployments based on new build plans in Bamboo.

You connect to Bamboo using a Harness Bamboo connector.

Bamboo connector YAML
connector:
name: Bamboo
identifier: Bamboo
description: ""
orgIdentifier: default
projectIdentifier: Docs
type: Bamboo
spec:
bambooUrl: https://bamboo.dev.example.io
auth:
type: UsernamePassword
spec:
username: admin
passwordRef: bamboo
delegateSelectors:
- mydelegate
Service using Bamboo plans YAML
service:
name: Bamboo
identifier: Bamboo
tags: {}
serviceDefinition:
spec:
artifacts:
primary:
primaryArtifactRef: myplan
sources:
- identifier: myplan
spec:
connectorRef: Bamboo
artifactPaths: artifacts
build: 133
planKey: PLAN1
type: Bamboo
type: Ssh

Build plan permissions

Make sure the connected user account has the following required permissions to the Bamboo Server.

  • View plan.
  • Build plan (if you plan to trigger a build as part of your pipeline).

For more information, go to Bamboo Permissions.

Github packages

Use Github packages as artifacts

You can use Github Packages as artifacts for deployments.

Package type (packageType) support:

  • Docker
  • NPM
  • Maven
  • Nuget

You connect to GitHub using a Harness GitHub connector, username, and personal access token (PAT).

tip

New to Github Packages? This quick video will get you up to speed in minutes.

GitHub Packages connector YAML

connector:
name: GitHub Packages
identifier: GitHub_Packages
orgIdentifier: default
projectIdentifier: CD_Docs
type: Github
spec:
url: https://github.com/johndoe/myapp.git
validationRepo: https://github.com/johndoe/test.git
authentication:
type: Http
spec:
type: UsernameToken
spec:
username: johndoe
tokenRef: githubpackages
apiAccess:
type: Token
spec:
tokenRef: githubpackages
delegateSelectors:
- gcpdocplay
executeOnDelegate: true
type: Repo

Service using Github Packages artifact YAML

service:
name: Github Packages
identifier: Github_Packages
tags: {}
serviceDefinition:
spec:
manifests:
- manifest:
identifier: myapp
type: K8sManifest
spec:
store:
type: Harness
spec:
files:
- /Templates
valuesPaths:
- /values.yaml
skipResourceVersioning: false
enableDeclarativeRollback: false
artifacts:
primary:
primaryArtifactRef: <+input>
sources:
- identifier: myapp
spec:
connectorRef: GitHub_Packages
org: ""
packageName: tweetapp
packageType: container
version: latest
type: GithubPackageRegistry
type: Kubernetes

Permissions

The Github Personal Access Token (PAT) must have the write:packages and read:packages permissions.

Ensure that you enable API access in the Harness Github connector. In the Github connector YAML, the setting is apiAccess:

GitHub Packages connector YAML

connector:
name: GitHub Packages
identifier: GitHub_Packages
orgIdentifier: default
projectIdentifier: CD_Docs
type: Github
spec:
url: https://github.com/johndoe/myapp.git
validationRepo: https://github.com/johndoe/test.git
authentication:
type: Http
spec:
type: UsernameToken
spec:
username: johndoe
tokenRef: githubpackages
apiAccess:
type: Token
spec:
tokenRef: githubpackages
delegateSelectors:
- gcpdocplay
executeOnDelegate: true
type: Repo

You can use the same Harness secret that you used for user authentication.

Github packages artifact expressions

You can reference artifact properties using the following expressions in a values YAML file or in any Harness setting that supports Harness expressions.

ExpressionDescriptionExample
<+artifact.connectorRef>Identifier of the connector used by the artifact sourceorg.github
<+artifact.identifier>Identifier of the artifact source in the service definitionAcmeGithub
<+artifact.type>This will be GithubPackageRegistry alwaysGithubPackageRegistry
<+artifact.primaryArtifact>Boolean values. true in case of primary artifacttrue
<+artifact.version>This is the Docker tagv1
<+artifact.packageType>Type of package. It is one of container, maven, nuget, npmcontainer
<+artifact.image>This is the image of the particular version. The value is used with `docker pull` commandghcr.io/acme/helloworld:100
<+artifact.packageName>Name of the repository in Githubhelloworld
<+artifact.imagePullSecret>This will be the base64 encoded secret used for pulling the image
<+artifact.dockerConfigJsonSecret>This is the kubernetes.io/dockerconfigjson credentials. Valid for docker only
<+artifact.digest>This is the digest specified in the ECR artifact source definition. Valid for docker onlysha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.label.[PLACEHOLDER]>This is the label set in the Docker image. Replace the placeholder with the appropriate label. Valid for docker only
<+artifact.metadata.SHAV2>Docker supports v1 and v2 format. We list both the formats when applicable. Valid for docker onlysha256:6d001fb3022161cdcb5f4df6cca5b5705e064ce873cd16144c3e4de8d2653d0b
<+artifact.metadata.SHA>SHA of the Docker image. Valid for docker onlysha256:b3ebe55062b76860c6c0c78f5cae81ec393a944bcc96c05b5f411d3560c9f1d8

Custom artifact source

Use artifacts from a custom artifact source

For enterprises that use a custom repository, Harness provides the Custom Artifact Source.

To use this artifact source, you provide a script to query your artifact server via its API (for example, REST) and then Harness stores the output on the Harness Delegate in the Harness-initialized variable $HARNESS_ARTIFACT_RESULT_PATH.

The output must be a JSON array, with a mandatory key for a Build Number/Version. You then map a key from your JSON output to the Build Number/Version variable.

For steps on adding a Custom Artifact source, go to Add a custom artifact source for CD.

Artifact limits and display in the Harness UI

The following table lists how many artifact versions Harness displays in its UI drop-downs, and how Harness sorts the versions.

Artifact Source TypeLimitOrder
DockerRegistry10000Lexical (descending)
Google Container RegistryNo LimitLexical (descending)
AWS ECRNo LimitLexical (descending)
Azure Container Registry500Lexical (descending)
Google Artifact Registry(Docker)2,147,483,647Descending order of created at.
Artifactory(Docker)No LimitLexical (descending)
Artifactory(Generic)10000Descending order of created at.
Github PackagesNo LimitDescending order of created at.
Nexus3(Docker)50Descending order of last modified at (3.46.0 and newer). Alphabetically descending for older versions.
Nexus3(non-Docker)2,147,483,647Descending order of last modified at (3.46.0 and newer). Alphabetically descending for older versions.
Nexus2No LimitLexical (descending)
Amazon S3500Descending order of last modified.
Amazon Machine ImageNo LimitDescending order of image creation time.
Azure ArtifactsNo Limit
Jenkins25Lexical (descending)
CustomNo LimitThe same as the custom script used.

Pull an image from a private registry

Typically, if the Docker image you are deploying is in a private registry, Harness has access to that registry using the credentials set up in the Harness connector you use with your service Artifacts.

Credentials to access Docker builds

If some cases, your Kubernetes cluster might not have the permissions needed to access a private Docker registry.

For these cases, the values YAML file in Service Definition Manifests section must use the dockercfg parameter.

If the Docker image is added in the Service Definition Artifacts section, then you reference it like this: dockercfg: <+artifacts.primary.imagePullSecret>.

This key will import the credentials from the Docker credentials file in the artifact.

Open the values.yaml file you are using for deployment.

Verify that dockercfg key exists, and uses the <+artifacts.primary.imagePullSecret> expression to obtain the credentials:

name: <+stage.variables.name>  
replicas: 2

image: <+artifacts.primary.image>
dockercfg: <+artifacts.primary.imagePullSecret>

createNamespace: true
namespace: <+infra.namespace>
...

Reference dockercfg in Kubernetes objects

Next, verify that the Deployment and Secret objects reference dockercfg: {{.Values.dockercfg}}.

...  
{{- if .Values.dockercfg}}
apiVersion: v1
kind: Secret
metadata:
name: {{.Values.name}}-dockercfg
annotations:
harness.io/skip-versioning: true
data:
.dockercfg: {{.Values.dockercfg}}
type: kubernetes.io/dockercfg
---
{{- end}}

apiVersion: apps/v1
kind: Deployment
metadata:
name: {{.Values.name}}-deployment
spec:
replicas: {{int .Values.replicas}}
selector:
matchLabels:
app: {{.Values.name}}
template:
metadata:
labels:
app: {{.Values.name}}
spec:
{{- if .Values.dockercfg}}
imagePullSecrets:
- name: {{.Values.name}}-dockercfg
{{- end}}
containers:
- name: {{.Values.name}}
image: {{.Values.image}}
...

With these requirements met, the cluster imports the credentials from the Docker credentials file in the artifact.

warning

When selecting artifacts/tags in Harness dropdown menus, if the artifacts/tags use Harness expressions, please keep in mind that some expressions can’t be resolved outside of pipeline execution. For example, artifacts/tags expressions using <+project.name> or <+org.name> will not resolve to values in runtime dropdowns, including those used to load tags.

Sidecar workloads

You can use Harness to deploy both primary and sidecar Kubernetes workloads.

Kubernetes sidecar workloads are a powerful way to modularize and encapsulate application functionality while keeping the overall architecture simple and easy to manage.

Sidecars are commonly used to implement cross-cutting concerns like logging, monitoring, and security. By separating these concerns into separate containers, it's possible to add or modify them without affecting the primary container or the application running inside it.

For example, a logging sidecar can be used to capture and store application logs, metrics, and other data, without requiring the primary container to implement any logging code.

Sidecars can also be used to implement advanced features like load balancing, service discovery, and circuit breaking. By using a sidecar container for these features, it's possible to keep the primary container simple and focused on its core functionality, while still providing advanced capabilities to the application.

For more information, go to Add a Kubernetes sidecar container.

Propagate and override artifacts, manifests, and service variables

You can propagate services between stages and override service settings by using multiple values YAML files and/or Environment Overrides.

For more information, go to:

Viewing SHA values and labels

Harness provides expressions you can use to output the SHA values and labels of the Docker images for the following artifact providers:

  • Docker Registry (platform agnostic)
  • Artifactory
  • ECR
  • GCR
  • Google Artifact Registry
  • Nexus 3 Docker
  • ACR
  • Github Packages

SHA values and labels for the artifact are now visible in the Harness service Output section of a pipeline execution.

Labels are visible if the artifact manifest supports schemaVersion1.

Labels can be referenced using the expression: <+pipeline.stages.[stage Id].spec.artifacts.primary.label.get("labelKey")>.

Since manifests can support two schema versions, schemaVersion1 and schemaVersion2, there could be SHA values for each schema version.

Here are the expressions for referencing each version:

  • SHA value of schemaVersion1: <+artifacts.primary.metadata.SHA> (same stage) or <+pipeline.stages.[stage Id].spec.artifacts.primary.metadata.SHA>.
  • SHA value of schemaVersion2: <+artifacts.primary.metadata.SHAV2> (same stage) or <+pipeline.stages.[stage Id].spec.artifacts.primary.metadata.SHAV2>.

If the service is configured to use an image with a specific digest, you can access the digest using <+pipeline.stages.STAGE_ID.spec.artifacts.primary.digest>.