# Preview Environments for Feature Branches

This guide demonstrates how to use the Flux Operator ResourceSet API to automate the deployment of
applications from feature branches to preview environments for testing and validation.

The Flux Operator supports branch-based preview environments for the following Git providers
via the ResourceSetInputProvider
[`spec.type`](/docs/crd/resourcesetinputprovider/#type) field:

- `GitHubBranch`
- `GitLabBranch`
- `AzureDevOpsBranch`
- `GiteaBranch`

## Development workflow

- A developer creates a feature branch with a naming convention (e.g. `feat/` prefix) in the app repository.
- The CI builds and pushes the app container image tagged with the Git commit SHA.
- Flux Operator running in the preview cluster scans the repository and finds branches matching the configured pattern.
- Flux Operator installs a Helm release for each matching branch to deploy the app changes in the cluster.
- The app is accessible at a preview URL composed of the branch identifier and the app name.
- The developers iterate over changes, with each push to the branch triggering a Helm release upgrade in the cluster.
- The developers are notified of the deployment status via Slack and commit statuses on the Git provider.
- Once the branch is deleted (e.g. after the PR is merged), the Flux Operator uninstalls the Helm release from the cluster.

## GitOps workflow

To enable the development workflow, we'll define a series of Flux Operator custom resources in the preview cluster.
Note that the preview cluster must be provisioned with a [Flux Instance](/docs/crd/fluxinstance/) and the Kubernetes
manifests part of the GitOps workflow should be stored in the Git repository used by the Flux Instance.

### Preview namespace

First we'll create a dedicated namespace called `app-preview` where all the app instances generated
from feature branches will be deployed. We'll also create a service account for Flux that limits
the permissions to the `app-preview` namespace.

```yaml
apiVersion: v1
kind: Namespace
metadata:
  name: app-preview
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: flux
  namespace: app-preview
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: flux
  namespace: app-preview
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: admin
subjects:
  - kind: ServiceAccount
    name: flux
    namespace: app-preview
```

### Authentication

In the `app-preview` namespace, create a Kubernetes Secret
containing credentials that grant read access to the app repository.

```shell
echo $GITHUB_TOKEN | flux-operator -n app-preview create secret basic-auth git-auth \
  --username=flux \
  --password-stdin
```

### ResourceSet input provider

In the `app-preview` namespace, we'll create a [ResourceSetInputProvider](/docs/crd/resourcesetinputprovider/)
that tells Flux Operator to scan the repository for branches matching a pattern (e.g. `feat/`):

```yaml
apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSetInputProvider
metadata:
  name: app-branches
  namespace: app-preview
  annotations:
    fluxcd.controlplane.io/reconcileEvery: "10m"
spec:
  type: GitHubBranch
  url: https://github.com/org/app
  secretRef:
    name: git-auth
  filter:
    includeBranch: "feat/.*"
  defaultValues:
    chart: "charts/app"
```

The branch providers export the following inputs for use in the ResourceSet template:

| Input | Description |
|-------|-------------|
| `inputs.id` | A short identifier derived from the branch name, safe for use in Kubernetes resource names |
| `inputs.sha` | The latest commit SHA on the branch |
| `inputs.branch` | The branch name |

### Webhook

Optionally, we can create a Flux [Webhook Receiver](/docs/crd/receiver/)
to notify the Flux Operator when a branch is created, updated or deleted:

```yaml
apiVersion: notification.toolkit.fluxcd.io/v1
kind: Receiver
metadata:
  name: git-receiver
  namespace: app-preview
spec:
  type: github
  secretRef:
    name: receiver-token
  resources:
    - apiVersion: fluxcd.controlplane.io/v1
      kind: ResourceSetInputProvider
      name: app-branches
```

### ResourceSet template

To deploy the app from feature branches, we'll create a [ResourceSet](/docs/crd/resourceset/)
that takes its inputs from the `ResourceSetInputProvider`:

```yaml
apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSet
metadata:
  name: app
  namespace: app-preview
spec:
  serviceAccountName: flux
  inputsFrom:
    - apiVersion: fluxcd.controlplane.io/v1
      kind: ResourceSetInputProvider
      name: app-branches
  resources:
    - apiVersion: source.toolkit.fluxcd.io/v1
      kind: GitRepository
      metadata:
        name: app-<< inputs.id >>
        namespace: app-preview
      spec:
        interval: 1h
        url: https://github.com/org/app
        ref:
          commit: << inputs.sha >>
        secretRef:
          name: git-auth
    - apiVersion: helm.toolkit.fluxcd.io/v2
      kind: HelmRelease
      metadata:
        name: app-<< inputs.id >>
        namespace: app-preview
        annotations:
          event.toolkit.fluxcd.io/commit: << inputs.sha | quote >>
          event.toolkit.fluxcd.io/preview-url: "https://app-<< inputs.id >>.example.com"
          event.toolkit.fluxcd.io/branch: << inputs.branch | quote >>
      spec:
        serviceAccountName: flux
        interval: 10m
        releaseName: app-<< inputs.id >>
        chart:
          spec:
            chart: << inputs.chart >>
            reconcileStrategy: Revision
            sourceRef:
              kind: GitRepository
              name: app-<< inputs.id >>
        values:
          image:
            tag: << inputs.sha >>
          ingress:
            hosts:
              - host: app-<< inputs.id >>.example.com
```

The above `ResourceSet` will generate a Flux `GitRepository` and a `HelmRelease` for each matching branch.
The branch identifier passed as `<< inputs.id >>` is used as the name suffix for the Flux objects,
and is also used to compose the Ingress host name where the app can be accessed.

The latest commit SHA pushed to the branch is passed as `<< inputs.sha >>`,
the SHA is used to set the app image tag in the Helm release values.

The `commit` annotation is used by the Flux notification providers
to post commit statuses on the Git provider. The preview URL and branch name
are set as extra metadata to enrich the notifications that the dev team receives.

To verify the ResourceSet templates are valid, we can use the
[Flux Operator CLI](cli.md) and build them locally:

```shell
flux-operator build resourceset -f app-resourceset.yaml \
  --inputs-from test-inputs.yaml
```

The `test-inputs.yaml` file should contain mock branch data e.g.:

```yaml
   - branch: feat/test
     id: "123456"
     sha: bf5d6e01cf802734853f6f3417b237e3ad0ba35d
     chart: "charts/app"
```

### Notifications

To receive notifications when a branch triggers a Helm release install,
upgrade and uninstall (including any deploy errors),
a Flux [Alert](/docs/crd/alert/)
can be created in the `app-preview` namespace:

```yaml
---
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: slack-bot
  namespace: app-preview
spec:
  type: slack
  channel: general
  address: https://slack.com/api/chat.postMessage
  secretRef:
    name: slack-bot-token
---
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
  name: slack
  namespace: app-preview
spec:
  providerRef:
    name: slack-bot
  eventSources:
    - kind: GitRepository
      name: '*'
    - kind: HelmRelease
      name: '*'
  eventMetadata:
    cluster: "preview-cluster-1"
    region: "us-east-1"
```

### Commit status reporting

To report the deployment status as a commit check on the Git provider,
we can use the Flux [commit status providers](/docs/crd/provider/#git-commit-status).
This requires the HelmRelease to be annotated with the `commit` metadata key
as shown in the [ResourceSet template](#resourceset-template) above.

```yaml
---
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: commit-status
  namespace: app-preview
spec:
  type: github
  address: https://github.com/org/app
  secretRef:
    name: git-auth
---
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
  name: commit-status
  namespace: app-preview
spec:
  providerRef:
    name: commit-status
  eventSeverity: info
  eventSources:
    - kind: HelmRelease
      name: '*'
```

The commit status provider `spec.type` should match your Git provider: `github`, `gitlab`,
`azuredevops` or `gitea`.

Every time a commit is pushed to a feature branch, the Flux Operator will upgrade the Helm release
and will update the commit status with the latest deployment status.

## Further reading

To learn more about ResourceSets and the various configuration options, see the following docs:

- [ResourceSet API reference](/docs/crd/resourceset/)
- [ResourceSetInputProvider API reference](/docs/crd/resourcesetinputprovider/)