> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/3.0/in-harness-3.0/pipelines/services.md).

# Services & Environments

Services and Environments are core deployment concepts in Harness 3.0. A Service defines what you are deploying (application, container, function), and an Environment defines where you are deploying (dev, staging, production). Together, they configure the deployment target for a pipeline stage.

### Services <a href="#services" id="services"></a>

A Service represents the application or workload being deployed. It includes artifact references, manifests, configuration files, and variables that define the deployment payload.

#### Service schema <a href="#service-schema" id="service-schema"></a>

```typescript
interface Service {
  // Reference to a defined service entity
  ref: string

  // Inline service definition
  name: string

  // Service description
  description: string

  // Deployment type (kubernetes, native-helm, serverless, etc.)
  deployment_type: string

  // Artifact configuration
  artifacts: ArtifactConfig

  // Manifest configuration
  manifests: ManifestConfig[]

  // Config files
  config_files: ConfigFile[]

  // Service-level variables
  variables: Record<string, string>
}
```

#### Service definition <a href="#service-definition" id="service-definition"></a>

Define a service inline within the pipeline or reference a pre-configured service entity.

```yaml
# Inline service definition <a href="#inline-service-definition" id="inline-service-definition"></a>
stages:
  - name: deploy
    service:
      name: my-web-app
      deployment_type: kubernetes
      artifacts:
        primary:
          type: docker
          spec:
            connector: docker-hub
            image: my-org/web-app
            tag: ${{ inputs.version }}
      manifests:
        - type: k8s
          spec:
            store:
              type: git
              spec:
                connector: github
                paths:
                  - k8s/deployment.yaml
                  - k8s/service.yaml
    steps:
      - run: echo "Deploying ${{ service.name }}"
```

#### Single service reference <a href="#single-service-reference" id="single-service-reference"></a>

Reference a service defined at the project, organization, or account level. Service and environment can be specified at either the pipeline level or the stage level.

```yaml
# pipeline-level service and environment <a href="#pipeline-level-service-and-environment" id="pipeline-level-service-and-environment"></a>
# NOTE: service and environment are also supported <a href="#note-service-and-environment-are-also-supported" id="note-service-and-environment-are-also-supported"></a>
# at the stage level. <a href="#at-the-stage-level" id="at-the-stage-level"></a>

pipeline:
  service: my-web-app
  environment: production
  stages:
  - steps:
    - run: echo "Deploying service"
```

#### Multiple service references <a href="#multiple-service-references" id="multiple-service-references"></a>

Deploy multiple services in a single pipeline. By default, services are deployed in parallel.

```yaml
pipeline:
  service:
    items:
    - frontend-app
    - backend-api
    - worker-service
  environment: staging
  stages:
  - steps:
    - run: echo "Deploying ${{ service.name }}"
```

#### Sequential service deployment <a href="#sequential-service-deployment" id="sequential-service-deployment"></a>

Deploy services one at a time in a defined order using the `sequential` flag.

```yaml
pipeline:
  service:
    sequential: true
    items:
    - database-migration
    - backend-api
    - frontend-app
  environment: production
  stages:
  - steps:
    - run: echo "Deploying ${{ service.name }}"
```

{% hint style="info" %}
**SERVICE VARIABLES**

Each service can define its own variables accessible within the stage using `${{ service.variables.<name> }}`. Service variables override pipeline-level environment variables with the same name.
{% endhint %}

***

### Environments <a href="#environments" id="environments"></a>

An Environment represents a deployment target such as development, staging, or production. Environments define infrastructure mappings, overrides, and governance policies.

#### Environment schema <a href="#environment-schema" id="environment-schema"></a>

```typescript
interface Environment {
  // Reference to a defined environment entity
  ref: string

  // Inline environment name
  name: string

  // Environment description
  description: string

  // Environment type
  type: "production" | "non-production"

  // Infrastructure definitions
  infrastructures: InfrastructureRef[]

  // Environment-level overrides
  overrides:
    | { manifests: ManifestOverride[] }
    | { config_files: ConfigFileOverride[] }
    | { variables: Record<string, string> }
    
  // Service-specific overrides
  service_overrides: Record<string, OverrideConfig>
}
```

#### Environment types <a href="#environment-types" id="environment-types"></a>

| Type             | Description                                                                         | Governance                                                   |
| ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `production`     | Live customer-facing environments. Requires approvals and freeze window compliance. | Approval gates, freeze windows, audit logging enforced.      |
| `non-production` | Development, testing, and staging environments. Lighter governance requirements.    | Optional approvals, no freeze window enforcement by default. |

#### Environment definition <a href="#environment-definition" id="environment-definition"></a>

Reference an environment by name and specify the infrastructure to deploy to using the `deploy-to` field.

```yaml
pipeline:
  stages:
  - name: deploy
    service: my-app
    environment:
      name: staging
      deploy-to: k8s-staging-cluster
    steps:
    - run: echo "Deploying to ${{ environment.name }}"
```

***

### Multi-service deployment <a href="#multi-service-deployment" id="multi-service-deployment"></a>

Deploy multiple services to the same environment in a single stage. Services can be deployed in parallel (default) or sequentially.

#### Parallel service deployment <a href="#parallel-service-deployment" id="parallel-service-deployment"></a>

All services deploy simultaneously, reducing total deployment time. This is the default behavior when using `items`.

```yaml
pipeline:
  service:
    items:
    - user-service
    - order-service
    - payment-service
    - notification-service
  environment: staging
  stages:
  - steps:
    - run: |
        echo "Deploying ${{ service.name }}"
        kubectl apply -f k8s/${{ service.name }}/
```

{% hint style="info" %}
**SERVICE ITERATION**

When multiple services are specified, the stage steps execute once for each service. Use `${{ service.name }}` and `${{ service.ref }}` to reference the current service in expressions.
{% endhint %}

#### Sequential service deployment <a href="#sequential-service-deployment" id="sequential-service-deployment"></a>

Deploy services one after another, useful when services have startup order dependencies.

```yaml
pipeline:
  service:
    sequential: true
    items:
    - database-migration
    - cache-service
    - backend-api
    - frontend-app
  environment: production
  stages:
  - steps:
    - run: |
        echo "Deploying ${{ service.name }}"
        ./deploy.sh ${{ service.name }}
```

***

### Multi-environment deployment <a href="#multi-environment-deployment" id="multi-environment-deployment"></a>

Deploy the same service across multiple environments, such as promoting a release from staging to production through a sequence of environment targets.

#### Sequential environment deployment <a href="#sequential-environment-deployment" id="sequential-environment-deployment"></a>

Promote a release through multiple environments sequentially. Use `sequential: true` on the environment and the `deploy-to` field to specify infrastructure targets per environment.

```yaml
pipeline:
  service: my-app
  environment:
    sequential: true
    items:
    - name: dev
      deploy-to: k8s-dev
    - name: staging
      deploy-to: k8s-staging
    - name: production
      deploy-to:
      - k8s-prod-us-east
      - k8s-prod-us-west
  stages:
  - steps:
    - run: ./deploy.sh ${{ environment.name }}
```

#### Complete multi-service, multi-environment deployment <a href="#complete-multi-service-multi-environment-deployment" id="complete-multi-service-multi-environment-deployment"></a>

A comprehensive example combining multiple services and environments in a single pipeline.

```yaml
pipeline:
  service:
    items:
    - backend-api
    - frontend-app
  environment:
    sequential: true
    items:
    - name: dev
      deploy-to: k8s-dev
    - name: staging
      deploy-to:
      - k8s-staging-1
      - k8s-staging-2
    - name: production
      deploy-to: all
  stages:
  - steps:
    - run: |
        echo "Deploying ${{ service.name }} to ${{ environment.name }}"
        ./deploy.sh ${{ service.name }}
```

{% hint style="info" %}
**INFRASTRUCTURE TARGETING**

Use `deploy-to: all` to deploy to all infrastructures defined in the environment. You can also specify a single infrastructure as a string or a list of specific infrastructure targets.
{% endhint %}