Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Creating EnvironmentsService OverridesOverride PriorityInfrastructure DefinitionsInfrastructure TagsValues Yaml OverridesMerging Values YamlFully Overriding ValuesConfig FilesRuntime Inputs And ExpressionsEnvironments RbacEnvironment Groups

Environments overview

Understand Continuous Delivery environments, including infrastructure definitions, service overrides, override priority, and environment groups

A Harness environment represents where you are deploying your application. You categorize each environment as production or non-production.

Environments represent your deployment targets (QA, production, and so on). Each environment contains one or more Infrastructure Definitions that list your target clusters, hosts, and namespaces.

What you will learn from this topic


Environment structure

Each infrastructure definition in an environment defines the specific VM, Kubernetes cluster, or target infrastructure where you plan to deploy your application. An environment can contain multiple infrastructure definitions. When you select an environment in a pipeline, you can pick which infrastructure definition to use.

The service configuration overrides setting allows you to override service properties when a service is deployed into a specific environment.

Environment variables are global variables for that environment. You can use those variables in your pipelines, manifests, and other resources.

For example, you might have an environment that is production, and within that environment you have five infrastructure definitions representing the five Kubernetes clusters associated with the production environment.


Create environments

You can create environments from:

  • An Account

  • An Organization

  • Within a pipeline

  • Outside a pipeline

When you create an environment in a pipeline, it is automatically added to Environments. You can add the same environment to as many pipelines as you need.

For more information, go to create environments.

Create environments at an account or organization level

You can create an environment and provide infrastructure definitions at an account or organization level from the Harness UI, using APIs or Terraform.

To create an environment at an account or organization level, go to Organization Resources -> Environments.

Create environment from organization or account resources

Expand the section below to see a sample account level environment YAML.

Account level environment YAML

Expand the section below to see a sample account level infrastructure definition YAML.

Account level infrastructure definition YAML

Expand the section below to see a sample organization level environment YAML.

Organization level environment YAML

Expand the section below to see a sample organization level infrastructure definition YAML.

Organization level infrastructure definition YAML

For information about creating an environment API, go to create an environment.

For information about creating infrastructure definition API, go to create an infrastructure in an environment.

The orgIdentifier and projectIdentifier field definitions are optional, and depend on where you want to create the environment. For example, if you create an environment at an account level, you will not need org or project identifiers in the post API call payload.

For information about creating a Harness platform environment, go to harness_platform_environment (Resource).

Expand the section below to see a sample platform environment in Terraform.

Harness platform environment

For information about creating a Harness platform infrastructure definition, go to harness_platform_infrastructure (Resource).

Expand the section below to see a sample platform infrastructure definition in Terraform.

Harness platform infrastructure definition

The org_id and project_id field definitions are optional, and depend on where you want to create the environment. For example, if you create an environment at an account level, you will not need org or project identifiers.

Create environments inside a pipeline

To create an environment from inside of a pipeline, select New Environment in the Infrastructure tab of a new Deploy stage.

New Environment control in the Infrastructure tab of a Deploy stage

Create environments outside a pipeline

To create an environment from outside of a pipeline, go to Environments in the navigation pane.

Environments entry in the Harness navigation pane

Environment settings

After creating an environment, you can define all its settings:

  • Configuration: The default environment configuration, including variables, manifests, specifications, and config files that are used every time the environment is used in a stage.

  • Service Overrides: Override specific services. You select a service and define what is overridden whenever that service is deployed to this environment.

  • Infrastructure Definitions: Represent one or more environment infrastructures.

    • Infrastructure definitions are the actual clusters, hosts, and related resources where Harness deploys a service. For example, you might have a QA environment with separate Kubernetes clusters (infrastructure definitions) for each service you want to test.

    • You can add multiple infrastructure definitions to a single environment and select an infrastructure definition when you add the environment to a stage.

  • GitOps Clusters: Adding Harness GitOps clusters to an environment lets you select them as the deployment target in stages. For more information on Harness GitOps, go to Harness GitOps basics.

  • Referenced by: Displays the list of pipelines using the infrastructure definitions in the environment.

Configuration

In the environment Configuration, you can manage the Name, Description, Tags, and Environment Type of the environment.

Environment Configuration showing name, description, tags, and environment type

You can also set default manifests, specifications, config files, and variables to use whenever Harness deploys a service to this environment.

For example, a stage has a Kubernetes service with a manifest but whenever that service is deployed to the QA environment, the manifest in that environment's Configuration overwrites the namespace of the manifest in the service with QA.

Service overrides

Service overrides are different from Environment Configuration in the following ways:

  • Environment Configuration: Applies to every service that is used with the environment.

  • Environment Service Overrides: Applies to specific services you select. Whenever that service is used with that environment, the Service Override is applied.

Runtime inputs are not supported if you are trying to override services in multi-service and multi-environment set ups.

Override priority

When you use environment configuration and service overrides to override service settings, understand the priority of the overrides.

The priority from top to bottom is:

  1. Environment service overrides

  2. Environment configuration

  3. Service settings

Override priority from environment service overrides down to service settings

Override priority example

Suppose you have a pipeline that runs as follows:

  • Deploys a service named myService, which has a variable cpu set to 1.

  • Deploys myService to myEnvironmentAlpha, and then overrides the myService variable cpu value to 2.

In this case, the environment variable takes precedence, and overrides the service variable. When the pipeline runs, it uses the cpu value of 2.

Suppose you have another pipeline that deploys myService to myEnvironmentKappa, which has a service override that sets cpu to 4. In this case, the environment service override takes precedence over the environment configuration and the service setting. When the pipeline runs, it uses the cpu value of 4.

Infrastructure definitions

Infrastructure definitions represent an environment's infrastructures physically. They are the actual clusters, hosts, namespaces, and related resources where you deploy a service.

An environment can have multiple Infrastructure Definitions.

Infrastructure definitions listed on an environment

When you select an environment in a stage, you can select the Infrastructure Definition to use for that stage.

Select an infrastructure definition for a stage environment

Infrastructure definition scoping

During pipeline execution, all infrastructure definitions are displayed, regardless of whether they are scoped to the selected service. Manually ensure that only the appropriate infrastructure definitions are selected for your services. This limitation is more prominent when services or environments are dynamically expressed, as scoping may not apply consistently.

Infrastructure tags

Tags can be attached to infrastructure definitions representing their characteristics. These tags can be key value pairs.

Tags attached to an infrastructure definition

When you select the Infrastructure Definition for a stage, the attached tags can be accessed using their keys with the expression, <+infra.tags.tag_key>. This expression is available for use throughout the stage.

For example, you can skip certain steps in a pipeline based on the tags attached to the infrastructure.

Pipeline step conditioned on infrastructure tags

You can define allowed values in the Select Hosts settings under infrastructure. In the runtime view, a multi-select dropdown displays the predefined allowed values to choose from.


Values YAML overrides and merges

You can specify values YAML files at the environment's Service Overrides and Configuration, and the service itself.

Here is an example of specifying it at the environment's Configuration:

Values YAML specified in the environment Configuration

When you have a values YAML file at two or more of the environment Service Overrides, Environment Configuration, and the service itself, Harness merges the files into a single values YAML for deployment. This merging runs at pipeline execution runtime.

Overriding occurs when the higher priority setting has the same name:value pair as a lower priority setting.

Consider the following two examples.

Merge values YAML name:value pairs

An environment's Service Overrides values YAML has the name:value pair servicePort: 80 but no replicas name:value.

A service's Service Definition has a values YAML with replicas: 2 but no servicePort name:value.

At runtime, the two values YAML files are merged into one.

The servicePort: 80 from the environment Service Overrides values YAML is merged with the Service Definition's replicas: 2 in the values YAML:

Merged values.yaml combining environment service override and service definition keys

Fully override values YAML name:value pairs

An environment's Service Overrides values YAML has the name:value pairs replicas: 2 and servicePort: 80.

A service's Service Definition has a values YAML with replicas: 4 and servicePort: 8080.

At runtime, the name:value pairs from the environment Service Overrides values YAML fully override the service values YAML. The replicas: 2 and servicePort: 80 from the environment Service Overrides are used.

Environment service overrides fully replacing service values.yaml pairs

Config files and variables are completely overridden

Config files are a black box that can contain multiple formats and content, such as YAML, JSON, and plain text. Consequently, they cannot be overridden like Values YAML files.

Variables cannot be partially overridden either. They are completely replaced.

When you have Config files at two or more of the environment Service Overrides, Configuration, and the service itself, the standard override priority is applied.

When you have Variables with the same name at two or more of the environment Service Overrides, Configuration, and the service itself, the standard override priority is applied.


GitOps clusters

When you use Harness GitOps, you can add GitOps clusters to an environment.

For more information on Harness GitOps, go to Harness GitOps basics.

You can select your environment (Deployments -> Environments -> your environment), then select the GitOps Clusters tab to view the list of GitOps clusters associated with an environment. Each row's Cluster ID and Agent name is a link that opens the corresponding Cluster or Agent detail page in a new tab:

  • Cluster ID: Click to open the Cluster's detail page in a new tab.

  • Agent name: Click to open the linked Agent's detail page in a new tab.

Perform the following steps to add a cluster to this list:

  1. Click + Select Cluster at the top of the page.

  2. In the Select GitOps Clusters to add to Environment popup, select the scope tab (Project, Organization, or Account) to view clusters in that scope.

  3. Select the desired GitOps cluster from the list.

  4. Click Apply Selected. The selected cluster appears in the Environment's GitOps Clusters list.

GitOps Clusters list on an environment with Cluster ID and Agent columns

Next, when you create a pipeline, you can select the environment and the GitOps cluster(s) to use.

GitOps clusters selected on an environment for a pipeline

GitOps clusters are used in a PR pipeline. A PR pipeline creates and merges a Git PR on the config.json for a destination cluster as part of an ApplicationSet. The PR pipeline runs, merges a change to the config.json, and a GitOps sync on the ApplicationSet is initiated.

GitOps clusters are not used in standard Continuous Delivery pipelines. They are used only when you use GitOps.


Runtime inputs and expressions in environments

If you use runtime inputs in your environments, you must provide values for these when you run pipelines that use these environments.

If you use expressions in your environments, Harness must be able to resolve these expressions when you run pipelines that use these environments.

Select Runtime input for the environment.

Runtime input selected for an environment

When you run the pipeline, you can select the environment for runtime inputs.

Select environment values for runtime inputs at pipeline run

For more information on runtime inputs and expressions, go to Fixed Values, Runtime Inputs, and Expressions.


Environments RBAC

Go to RBAC in Harness for examples of RBAC use cases for environments.

Access permission is needed to deploy to an environment

One of the most important advantages of environments is the ability to define roles that determine who can deploy them.

For a role to allow deployments using environments, the role must have the access permission enabled for environments.

Access permission for Environments in a role

The View, Create, Edit, Delete, and Manage permissions enable you to deploy an environment.

If a role does not have the Access permission for Environments, a user or user group assigned that role cannot deploy to any environment.

Restrict access to specific environments for a user or user group

You can restrict a user or user group to using specific environments only.

Perform the following steps to restrict a user or user group to deploying to a specific environment only:

  1. Create a resource group and select the environment.

  2. Create a role and give the user or user group permissions. The Access permission is needed for deployments.

  3. Assign the role and resource group to the user or user group.

Resource group restricting a role to specific environments

Metadata sync with bidirectional sync

When you store environments and infrastructure definitions remotely in Git with bidirectional sync enabled, Harness automatically syncs entity metadata (name, description, and tags) back to Harness when those fields are updated on the Git side for the default branch.

Previously, modifying environment or infrastructure metadata directly in the Git repository did not propagate those changes to Harness, requiring a separate update from the Harness UI. With metadata sync, any change committed to the default branch in Git is reflected in Harness automatically. This sync applies only to the default branch; metadata changes on other branches are not synced.

Feature flag required

This feature is behind the feature flag CDS_GITX_WEBHOOK_SYNC_ENTITY_METADATA. Contact Harness Support to enable it.


Environment groups

Environment groups are a way to group environments so you can assign permissions to multiple environments in a role.

Environment group containing multiple environments

Next steps

Last updated

Was this helpful?