From 33ef2a2d12cd609390152977965e5592cc6285a6 Mon Sep 17 00:00:00 2001 From: Timo Behrendt Date: Wed, 29 Apr 2026 19:44:03 +0200 Subject: [PATCH] docs: finish docs --- README.md | 156 +++++++++++++----------------------------------------- 1 file changed, 38 insertions(+), 118 deletions(-) diff --git a/README.md b/README.md index 1395b3e..5cd0e4a 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,75 @@ -> [!WARNING] -> Repo is currently not in use and not tested. -> We are waiting for proper shared workflow UI support in gitea. Otherwise errors are hard to identify. -> Follow https://github.com/go-gitea/gitea/issues/24604 +# Reusable CI/CD Workflows for k\_ Services -# Reusable CI Workflow for Kubernetes Services - -This directory contains a reusable CI workflow that automatically detects and validates your Kubernetes services, whether they use Helm + Kubernetes or just Kubernetes manifests. +This repository contains reusable CI and CD workflows that automatically detect Kubernetes service type (Kubernetes-only vs Helm + Kubernetes) and execute the relevant steps. ## Features -- **Automatic Detection**: Automatically detects if your service uses Helm (helmfile.yaml) or just Kubernetes manifests -- **Conditional Validation**: Only runs Helm validation when helmfile.yaml exists -- **Flexible Paths**: Configurable paths for k8s directory and helmfile -- **Comprehensive Validation**: Validates both Kubernetes manifests and Helm charts -- **CI Summary**: Provides a clear summary of what was validated +- **Reusable CI and CD**: Separate reusable workflows for validation and deployment +- **Automatic Detection**: Detects whether `helmfile.yaml` exists and whether `k8s/` exists +- **Conditional Execution**: Runs Helm steps only when applicable +- **Flexible Inputs**: Supports custom `k8s_dir` and `helmfile_path` ## Usage -### Basic Usage (Recommended) +### Basic CI Usage -Simply call the workflow without any parameters - it will automatically detect your service type: +Call the reusable CI workflow: ```yaml jobs: ci: - uses: ./.gitea/workflows/ci.yaml + uses: https://gitea.t000-n.de/t.behrendt/k_deploy_workflows/.gitea/workflows/ci.yaml@main + secrets: inherit ``` -### Advanced Usage with Custom Paths +### Basic CD Usage -If your service uses non-standard directory names: +Call the reusable CD workflow: + +```yaml +jobs: + deploy: + uses: https://gitea.t000-n.de/t.behrendt/k_deploy_workflows/.gitea/workflows/cd.yaml@main + secrets: inherit +``` + +### Advanced Usage with Custom Paths and Flags ```yaml jobs: ci: - uses: ./.gitea/workflows/ci.yaml + uses: https://gitea.t000-n.de/t.behrendt/k_deploy_workflows/.gitea/workflows/ci.yaml@main with: k8s_dir: "kubernetes/" helmfile_path: "helm/helmfile.yaml" -``` - -### Force Skip Helm Validation - -If you want to skip Helm validation even when helmfile.yaml exists: - -```yaml -jobs: - ci: - uses: ./.gitea/workflows/ci.yaml - with: skip_helm_validation: true + secrets: inherit ``` -## Input Parameters +## Inputs + +### CI (`.gitea/workflows/ci.yaml`) | Parameter | Description | Default | Required | | ---------------------- | -------------------------------------------- | --------------- | -------- | | `k8s_dir` | Path to Kubernetes manifests directory | `k8s/` | No | | `helmfile_path` | Path to helmfile.yaml | `helmfile.yaml` | No | | `skip_helm_validation` | Skip Helm validation even if helmfile exists | `false` | No | +| `helmfile_env` | JSON object string passed as env to helmfile | `{}` | No | + +### CD (`.gitea/workflows/cd.yaml`) + +| Parameter | Description | Default | Required | +| -------------------------------- | -------------------------------------------- | --------------- | -------- | +| `k8s_dir` | Path to Kubernetes manifests directory | `k8s/` | No | +| `helmfile_path` | Path to helmfile.yaml | `helmfile.yaml` | No | +| `skip_helm_deployment` | Skip Helm deployment even if helmfile exists | `false` | No | +| `skip_shared_secrets_deployment` | Skip shared secrets deployment | `false` | No | +| `helmfile_env` | JSON object string passed as env to helmfile | `{}` | No | ## Directory Structure Requirements -### For Kubernetes-only services: - -``` -your-service/ -├── k8s/ -│ ├── deployment.yaml -│ ├── service.yaml -│ └── ... -└── .gitea/workflows/your-workflow.yaml -``` - -### For Helm + Kubernetes services: +### Full example structure (Helm + Kubernetes): ``` your-service/ @@ -84,79 +80,3 @@ your-service/ ├── helmfile.yaml └── .gitea/workflows/your-workflow.yaml ``` - -## What Gets Validated - -### Always (if k8s/ directory exists): - -- Kubernetes manifest validation using `kubectl --dry-run` -- Namespace extraction from repository name -- Basic Kubernetes syntax and schema validation - -### Conditionally (if helmfile.yaml exists and Helm validation not skipped): - -- Helm chart validation using `helmfile diff` -- Kubernetes manifests in Helm context -- Helm-specific configurations and values - -## Example Workflows - -See `example-usage.yaml` for complete examples of how to use this workflow in different scenarios. - -## Available Actions - -### Extract Chart Name from Repository Name - -The `extract-chart-name-from-repo-name` action extracts the chart name from repository names following the `helm-` convention. - -#### Usage - -```yaml -- name: Extract chart name - uses: ./.gitea/actions/extract-chart-name-from-repo-name - with: - repo: ${{ github.repository_name }} # e.g., "helm-my-service" -``` - -#### Inputs - -| Parameter | Description | Required | -| --------- | ------------------------------------------------ | -------- | -| `repo` | The full repository name (e.g., "helm-my-chart") | Yes | - -#### Outputs - -| Output | Description | -| ------------ | ---------------------------------------------------------------- | -| `chart-name` | The extracted chart name (e.g., "my-chart" from "helm-my-chart") | - -#### Example - -For a repository named `helm-user-service`, this action will extract `user-service` as the chart name. - -## Dependencies - -This workflow requires: - -- `./.gitea/actions/extract-namespace-from-repo-name` action -- `./.gitea/actions/extract-chart-name-from-repo-name` action -- `KUBECONFIG` secret configured in your repository -- Access to your Kubernetes cluster - -## Troubleshooting - -### Helm validation skipped unexpectedly - -- Check if `helmfile.yaml` exists in the expected location -- Verify the `skip_helm_validation` parameter is not set to `true` -- Ensure the file path is correct if using custom paths - -### Kubernetes validation skipped - -- Verify the `k8s/` directory (or custom path) exists -- Check the directory contains valid Kubernetes manifests - -### Permission issues - -- Ensure the `KUBECONFIG` secret is properly configured -- Verify the workflow has access to your Kubernetes cluster