README.md.gotmpl

# Atlantis

[Atlantis](https://www.runatlantis.io/) is a tool for safe collaboration on [Terraform](https://www.terraform.io/) repositories.

{{ template "chart.maintainersSection" . }}

{{ template "chart.requirementsSection" . }}

## Links

- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Required Configuration](#required-configuration)
- [Additional manifests](#additional-manifests)
- [Values](#values)
- [Upgrading](#upgrading)
  - [From `4.*` to `5.*`](#from-4-to-5)
  - [From `2.*` to `3.*`](#from-2-to-3)
  - [From `1.*` to `2.*`](#from-1-to-2)
- [Testing the Deployment](#testing-the-deployment)
- [Update documentation](#update-documentation)
- [Run unit tests](#run-unit-tests)

## Introduction

This chart creates a single pod in a StatefulSet running Atlantis. Atlantis persists Terraform [plan files](https://www.terraform.io/docs/commands/plan.html) and [lockfiles](https://www.terraform.io/docs/state/locking.html) to disk for the duration of a Pull/Merge Request. These files are stored in a PersistentVolumeClaim to survive Pod failures.

## Prerequisites

- Kubernetes 1.9+
- PersistentVolume support

## Required Configuration

In order for Atlantis to start and run successfully:

1. At least one of the following sets of credentials must be defined:
    - `github`
    - `gitea`
    - `gitlab`
    - `bitbucket`
    - `azuredevops`

    Refer to [values.yaml](/charts/atlantis/values.yaml) for detailed examples.
    They can also be provided directly through a Kubernetes `Secret`, use the variable `vcsSecretName` to reference it.

1. Supply a value for `orgAllowlist`, e.g. `github.com/myorg/*`.

## Additional manifests

It is possible to add additional manifests into a deployment, to extend the chart. One of the reason is to deploy a manifest specific to a cloud provider ( BackendConfig on GKE for example ).

```yaml
extraManifests:
  - apiVersion: cloud.google.com/v1beta1
    kind: BackendConfig
    metadata:
      name: "{{ `.Release.Name` }}-test"
    spec:
      securityPolicy:
        name: "gcp-cloud-armor-policy-test"
```

{{ template "chart.valuesSection" . }}

## Upgrading

### From `4.*` to `5.*`

A breaking change was merged on [#304](https://github.com/runatlantis/helm-charts/pull/304).
This change moves the atlantis data volume to a separate PVC to allow changing the volume size without removing the statefulset.
Unmistakingly, this change only bumped the minor version, released as `4.22.0`, instead of incrementing the major version. The release `5.0.0` addresses this issue. Please find the required upgrade manual steps below.

#### Upgrade steps


Trying to upgrade the release directly will return the following error:

> Error: UPGRADE FAILED: cannot patch "atlantis" with kind StatefulSet: StatefulSet.apps "atlantis" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'ordinals', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden

To allow the upgrade to proceed, first we need to remove the statefulset controller, copy all the data from the old volume to the new one and then cleanup.

NOTE: These steps will ensure no data is lost, however during the copy process the atlantis server is unavailable and any webhooks sent to atlantis during that window are missed and won't be processed.

Upgrade steps:

1. For atlantis deployments managed by GitOps solutions such as ArgoCD, disabling the automatic synchronization is required

1. Create a temporary helm configuration file named `migration-4-to-5.yaml`, the configuration includes the required settings to allow the atlantis data to be copied to the new volume before the atlantis server is started. The suggested configuration implies that the default command for atlantis has not been customized. If required, adjust the `persistentVolumeClaim.claimName` value.

    ```yaml
    command:
      - sh
      - -c
      - 'cp -Rv /atlantis-data-old/* "${ATLANTIS_DATA_DIR}" && exec /usr/local/bin/docker-entrypoint.sh server'

    extraVolumes:
      - name: atlantis-data-old
        persistentVolumeClaim:
          claimName: atlantis-data-atlantis-0

    extraVolumeMounts:
      - name: atlantis-data-old
        mountPath: /atlantis-data-old
    ```

1. Delete the current statefulset without removing the atlantis pod. This can be achieved with the parameter [--cascade=orphan](https://kubernetes.io/docs/tasks/administer-cluster/use-cascading-deletion/#set-orphan-deletion-policy):

    NOTE: If required, adjust the namespace and the statefulset name.

    ```sh
    kubectl delete statefulsets.apps atlantis --namespace atlantis --cascade=orphan
    ```

1. Deploy the new atlantis version, this will recreate the statefulset and update the atlantis pod acordingly. E.g.:

    ```sh
    helm upgrade -i atlantis runatlantis/atlantis --version 5.0.0 -f my-config.yaml -f migration-4-to-5.yaml
    ```

1. Check the logs for the atlantis pod, it should show the copy process followed by start of the atlantis server. E.g.:

    ```json
    '/atlantis-data-old/atlantis.db' -> '/atlantis-data/atlantis.db'
    '/atlantis-data-old/bin' -> '/atlantis-data/bin'
    '/atlantis-data-old/existing-data.example' -> '/atlantis-data/existing-data.example'
    '/atlantis-data-old/plugin-cache' -> '/atlantis-data/plugin-cache'
    No files found in /docker-entrypoint.d/, skipping
    {"level":"info","ts":"2024-05-01T17:17:03.406Z","caller":"server/server.go:447","msg":"Utilizing BoltDB","json":{}}
    {"level":"info","ts":"2024-05-01T17:17:03.411Z","caller":"policy/conftest_client.go:153","msg":"failed to get default conftest version. Will attempt request scoped lazy loads DEFAULT_CONFTEST_VERSION not set","json":{}}
    {"level":"info","ts":"2024-05-01T17:17:03.413Z","caller":"server/server.go:985","msg":"Atlantis started - listening on port 4141","json":{}}
    {"level":"info","ts":"2024-05-01T17:17:03.413Z","caller":"scheduled/executor_service.go:51","msg":"Scheduled Executor Service started","json":{}}
    ```

1. Run a second deployment without the extra configuration file. E.g.:

    ```sh
    helm upgrade -i atlantis runatlantis/atlantis --version 5.0.0 -f my-config.yaml
    ```

1. Remove the old `persistentVolumeClaim`:

    ```sh
    kubectl delete persistentvolumeclaims atlantis-data-atlantis-0 --namespace atlantis
    ```

1. For atlantis deployments managed by GitOps solutions such as ArgoCD, the automatic synchronization can now be enabled

### From `4.0.*` to `4.1.*`

- The following value are deprecated:
  - `dataStorage`
  - `storageClassName`

- In favor of the new working way:
  - `volumeClaim.enabled`
  - `volumeClaim.dataStorage`
  - `volumeClaim.storageClassName`

### From `2.*` to `3.*`

- The following value names have been removed. They are replaced by [Server-side Repository Configuration](https://www.runatlantis.io/docs/server-side-repo-config.html)
  - `requireApproval`
  - `requireMergeable`
  - `allowRepoConfig`

To replicate your previous configuration, run Atlantis locally with your previous flags and Atlantis will print out the equivalent repo-config, for example:

```bash
$ atlantis server --allow-repo-config --require-approval --require-mergeable --gh-user=foo --gh-token=bar --repo-allowlist='*'
WARNING: Flags --require-approval, --require-mergeable and --allow-repo-config have been deprecated.
Create a --repo-config file with the following config instead:

---
repos:
- id: /.*/
  apply_requirements: [approved, mergeable]
  allowed_overrides: [apply_requirements, workflow]
  allow_custom_workflows: true

or use --repo-config-json='{"repos":[{"id":"/.*/", "apply_requirements":["approved", "mergeable"], "allowed_overrides":["apply_requirements","workflow"], "allow_custom_workflows":true}]}'
```

Then use this YAML in the new repoConfig value:

```yaml
repoConfig: |
  ---
  repos:
  - id: /.*/
    apply_requirements: [approved, mergeable]
    allowed_overrides: [apply_requirements, workflow]
    allow_custom_workflows: true
```

### From `1.*` to `2.*`

- The following value names have changed:
  - `allow_repo_config` => `allowRepoConfig`
  - `atlantis_data_storage` => `dataStorage` **NOTE: more than just a snake_case change**
  - `atlantis_data_storageClass` => `storageClassName` **NOTE: more than just a snake_case change**
  - `bitbucket.base_url` => `bitbucket.baseURL`

## Testing the Deployment

To perform a smoke test of the deployment (i.e. ensure that the Atlantis UI is up and running):

1. Install the chart. Supply your own values file or use `test-values.yaml`, which has a minimal set of values required in order for Atlantis to start.

    ```bash
    helm repo add runatlantis https://runatlantis.github.io/helm-charts
    helm install -f test-values.yaml my-atlantis runatlantis/atlantis --debug
    ```

1. Run the tests:

    ```bash
    helm test my-atlantis
    ```

## Update documentation

Documentation is auto-generated using [helm-docs](https://github.com/norwoodj/helm-docs).

To update run the following (from the root path of the repository):

1. If required, update `charts/atlantis/README.md.gotmpl`
2. Run `make docs`

## Run unit tests

From the root of the repository, run:

```sh
make unit-test-run-atlantis
```

{{ template "helm-docs.versionFooter" . }}