Getting Started with the Application Promotion Pipeline¶

This guide provides a comprehensive overview of how to use the Application Promotion Pipeline to automate infrastructure changes for your application. It covers the core workflow, the configuration resources, and provides examples of how to define promotion paths.

How It Works¶

The service is powered by a Kubernetes operator, the Promotion Controller, whose primary purpose is to enable the deployment of resources that may require elevated permissions (e.g., cluster-wide resources). It achieves this by watching a Git repository for changes and promoting them through a configurable, Pull Request-based workflow.

graph LR
    subgraph "Customer Application Repository"
        PSD["Promotion Source Directory"]
    end

    subgraph "Kubernetes Cluster"
        subgraph "netic-gitops-system"
            PC["Promotion Controller"]
            FSC["Flux Source Controller"]
            FKC["Flux Kustomize Controller"]
        end

        subgraph "Customer Application Namespace"
            direction TB
            D["Deployment"]
            CRD["CRD"]
            CR["ClusterRole"]
        end

        FSC --> FKC
    end

    subgraph "Contain Managed Repository"
        PDD["Promotion Destination Directory"]
    end

    PC -- pulls --> PSD
    FKC --> D
    FKC --> CRD
    FKC --> CR
    PC -- pushes --> PDD
    FSC -- pulls --> PDD

Hold "Alt" / "Option" to enable pan & zoom

The Automated Workflow¶

The Promotion Controller operates in a continuous reconciliation loop that follows these steps:

Monitoring: The controller watches a specified directory in your source application Git repository for any changes.
Detection and Push: When a change is detected, the controller automatically pushes the modified files to a dedicated branch in a central cluster destination Git repository.
CI Pipeline Trigger: This push to the destination repository can automatically trigger a CI pipeline to handle the promotion flow.
Pull Request Generation: The CI pipeline (or the controller itself) creates a Pull Request (PR) containing the changes.
Automated vs. Manual Promotion: Based on a set of defined "promotion paths," the PR is either automatically merged (fast-forward) or left for manual review and approval (pull-request).
Deployment: Once the changes are merged into the cluster repository's main branch, a GitOps tool like Flux detects the new commits and automatically synchronizes the Kubernetes cluster with the new configuration.

Configuration¶

The entire process is configured using a custom Kubernetes resource called InfraUpdateAutomation. This resource acts as the bridge between your application repository and the central cluster repository.

`InfraUpdateAutomation` Resource Example¶

This resource defines the source repository to monitor and the destination repository where the controller will push changes.

apiVersion: infra.netic.dk/v1alpha1
kind: InfraUpdateAutomation
metadata:
  name: my-app-promotion
  namespace: my-app
spec:
  source:
    # The path within the source repository to monitor for changes.
    path: .infra
    ref:
      # A reference to a Flux GitRepository resource for the source.
      kind: GitRepository
      name: my-app-repo
      namespace: my-app
  target:
    git:
      commit:
        author:
          email: automation@myapp.com
      push:
        # A template for the branch name created in the target repo.
        branchTemplate: infra/my-cluster/{{ .Namespace }}-{{ .Name }}
    # The path within the target repository to write the changes to.
    path: clusters/my-cluster/prod/namespace-resources/my-app
    ref:
      # A reference to a Flux GitRepository resource for the target.
      kind: GitRepository
      name: cluster-repo
      namespace: netic-gitops-system

Defining Promotion Paths¶

The "Promotion Path" is a configurable DSL that defines how a change should be promoted. You can define different rules for various resource kinds, allowing for granular control over the deployment pipeline.

Minimal Example: Default Pull Request¶

This is the simplest configuration. It defines a single default step that requires a pull request for all changes.

name: default
steps:
  - name: "default"
    description: "Default pipeline for all promotions"
    details:
      transitions: ["pull-request"]

Targeting Specific Kinds: Fast-Forward for Deployments¶

You can create specific rules for certain Kubernetes resources. In this example, any changes to Deployment resources will be promoted automatically without a pull request.

name: app-deployments
kinds:
  - apiVersion: apps/v1
    kind: Deployment
steps:
  - name: "default"
    description: "Default for Deployment resources"
    details:
      transitions: ["fast-forward"]

Full Configuration Example¶

In a typical setup, you combine multiple promotion path definitions to handle different scenarios. The controller selects the most specific path that matches the changes.

Here, two paths are defined:

default: The fallback path. It applies to any resource that doesn't match a more specific rule and requires a manual pull request.
crd-fast-forward: This path applies only if changes are made to CustomResourceDefinition resources. It allows these changes to be merged automatically.

---
# Promotion Path 1: The Default Fallback
name: default
steps:
  - name: "default"
    description: "Default pipeline for all promotions"
    details:
      transitions: ["pull-request"]
---
# Promotion Path 2: Specific rule for CRDs
name: crd-fast-forward
kinds:
  - apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
steps:
  - name: "crd-promotion"
    description: "Fast-forward promotion for CRDs"
    details:
      transitions: ["fast-forward"]

Multi-Step Pipelines¶

For more complex scenarios, such as promoting between environments, you can define multiple steps within a single promotion path.

name: multi-env-promotion
kinds:
  - apiVersion: apps/v1
    kind: Deployment
steps:
  - name: to-test-env
    description: "Promote application from DEV to TEST"
    details:
      name: "moving-to-test"
      source: # ... define source details
      destination:
        repository:
          name: my-cluster-repo
          url: https://github.com/my-org/cluster-repo
          branch: main
          path: deploy/test
      transitions: [fast-forward]
  - name: to-prod-env
    description: "Promote application from TEST to PROD"
    details:
      name: "moving-to-prod"
      # ... define further steps
      transitions: [pull-request] # Require PR for production

Next Steps¶

To get started, you will need to:

Structure your application repository with the Kubernetes manifests you want to manage.
Create an InfraUpdateAutomation manifest to define your promotion pipeline's source and target.
Define one or more Promotion Path configurations.
Apply these resources to your Kubernetes cluster.

Please contact us if you need help to set up your first Application Promotion Pipeline.