Flux

Note

Primary audience: Skyscrapers customers, Skyscrapers internal

Introduction

Flux is a way to deploy and maintain your applications and components through GitOps. It is designed to keep your Kubernetes clusters in sync based on the configuration in git and to automate updates to configuration when Flux detects it. This documentation provides guidance on setting up and managing your repository structure using Flux in the cooperation with Skyscrapers.

In short, this means Flux will pull your changes from Git and keep everything reconciled. For example if you commit a neww container image to your helm chart, Flux will detect this and perform a helm upgrade directly from within the Kubernetes cluster. You are also not limited to Helm, Flux works great with Kustomize too.

• Flux
• Introduction
• Initial setup
• Repository Structure
  • Directory Breakdown
  • Applications
• Example Configuration
  • kustomization.yaml
  • apps.yaml
  • Internal within the same repository
  • External repository
• Monitoring
  • Slack Alerts
  • Grafana Dashboards
  • Flux Cluster Stats
  • Flux Control Plane
• ECR access

Initial setup

If you think this could be useful for your team, get in touch with us so we can enable it on your cluster(s), and offer you guidance and training on how to leverage it for your use-case.

Once the initial bootstrap is done, you can start managing your applications and infrastructure using Flux based.

Repository Structure

The recommended structure for organizing your Flux configurations and related resources in the repository is as follows:

docs/
flux/
├── apps/
    ├── base/
    ├── production/
    └── staging/
└── clusters/
    ├── production-cluster-name/
        ├── flux-system/
            └── ...
        └── apps.yaml
    └── staging-cluster-name/
        ├── flux-system/
            └── ...
        └── apps.yaml
k8s-clusters/
├── production-cluster-name.yaml
└── staging-cluster-name.yaml
terraform/
├── live/
└── modules/

Directory Breakdown

flux/: Directory to hold all Flux-related configuration files.

• apps/: Optional directory to organize application configurations.
• base/: Base configurations for all environments.
• production/: Specific configurations for the production environment.
• staging/: Specific configurations for the staging environment.
• clusters/: Directory for managing cluster-specific configurations.
• production-cluster-name/: Configuration for the production cluster.
  • flux-system/: Contains the core Flux system configurations. This is automatically provisioned for you by Skyscrapers/Flux and can't be modified manually.
  • apps.yaml: Kustomization overlay pointing to the apps folder or repository. See Applications section for more information.
• staging-cluster-name/: Configuration for the staging cluster, structured similarly to the production cluster.

Applications

To allow for more flexibility for your applications, you can point to a separate repository in the apps.yaml. This way you can still manage your application manifests within your own git repository, while still having Flux deploy them. The only requirement for this is that you define a GitRepository and create a Secret in the flux-system namespace with an SSH deploy key to access the repository. Example:

---
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: my-apps
  namespace: flux-system
spec:
  interval: 1m0s
  ref:
    branch: main
  secretRef:
    name: apps-deploykey
  url: ssh://git@github.com/<organisation>/<repo-name>.git

Example Configuration

This section provides some examples of the configuration files used to manage Flux resources. A for more in depth explanation of the configuration files, please refer to the Flux documentation or reach out to us.

kustomization.yaml

The kustomization.yaml file is used to manage resources in a structured way. In this file you refer to all files that you want Kustomize to include. An example configuration might look like:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - monitoring.yaml
  - scaling.yaml

apps.yaml

This file points to the applications folder or repository, allowing Flux to manage application deployments. An example configuration might be:

Internal within the same repository

apiVersion: kustomize.toolkit.fluxcd.io/v1beta1
kind: Kustomization
metadata:
  name: apps
  namespace: flux-system
spec:
  interval: 10m
  path: ./flux/apps/production
  sourceRef:
    kind: GitRepository
    name: flux-system

External repository

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: app
spec:
  url: ssh://git@github.com/<organisation>/<repo-name>.git
  ref:
    branch: main
  secretRef:
    name: apps-deploykey
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: app
spec:
  sourceRef:
    kind: GitRepository
    name: app
  path: flux/app/production

Tip

Requirement for this is that a secret (called apps-deploykey here in this example) is deployed in the flux-system namespace with an SSH deploy key to access the repository.

Monitoring

Slack Alerts

Out of the box Flux alerts in the shared Slack channel for errors. The destination channel and severity can be configured to your liking. Please reach out to us if you want to change the configuration or add more alerts.

Grafana Dashboards

There are 2 Grafana dashboards available in your Grafana for monitoring Flux:

Flux Cluster Stats

This dashboard provides an overview on the overall status of all objects managed by Flux.

Flux Control Plane

This dashboard provides an overview of the Flux system components and their health status.

ECR access

Note

Primary audience: Skyscrapers internal

If AWS ECR is used as registry, Skyscrapers commonly needs to setup cross-account access to ECR repositories. Instructions can be found in the AWS ECR documentation.