From f35e7b42dbb505967fec1dcdc3a73bee856673b1 Mon Sep 17 00:00:00 2001 From: Kingdon Barrett Date: Tue, 11 Jul 2023 11:50:55 -0400 Subject: [PATCH 1/2] Mark some use-cases doc in need of refresh The use-cases docs that are not covered here are all ones intended to be migrated into the Installation guides, per the GSoD plan that is being advanced here. So the use-cases section of the docs may go away entirely, (unless some of these docs turn out to survive all this without getting relocated): https://github.com/fluxcd/website/issues/1560 * strengthen some language And break out one of the longer texts into an "info" class message, "Author's Note" Open to suggestions about how to change this to look more Production * ambient credentials used to secure better language karmada condense two disclaimers into one I don't think we will archive the Karmada doc, since it was contributed by an outside person and it is a CNCF Sandbox project, but I'm giving it the same disclaimer as I'm giving all the docs as they're under review. * Remove note from helm promotion guide that was reviewed (fixup) Signed-off-by: Kingdon Barrett * add warning to e2e guide Signed-off-by: Kingdon Barrett --- content/en/flux/flux-e2e.md | 6 ++++++ .../en/flux/use-cases/gh-actions-app-builder.md | 10 +++++++++- content/en/flux/use-cases/gh-actions-auto-pr.md | 6 ++++++ .../use-cases/gh-actions-manifest-generation.md | 14 ++++++++++++++ content/en/flux/use-cases/jenkins.md | 6 ++++++ content/en/flux/use-cases/karmada.md | 4 ++++ 6 files changed, 45 insertions(+), 1 deletion(-) diff --git a/content/en/flux/flux-e2e.md b/content/en/flux/flux-e2e.md index d8da9db0a..84d550f4c 100644 --- a/content/en/flux/flux-e2e.md +++ b/content/en/flux/flux-e2e.md @@ -5,6 +5,12 @@ description: "A narrative of the life of a commit as it relates to Flux componen weight: 146 --- +{{% alert color="warning" title="Disclaimer" %}} +Note that this guide has not been updated since more than a year ago, it does not address `OCIRepository`, and needs to be refreshed for Flux 2.0.0. + +Expect this doc to receive an overhaul soon. +{{% /alert %}} + Below we describe the flow of data through Flux, from End to End. We assume a standard Flux installation, with all optional features enabled, then explain how Flux users can expect their change to flow through the stages diff --git a/content/en/flux/use-cases/gh-actions-app-builder.md b/content/en/flux/use-cases/gh-actions-app-builder.md index a1811e428..8726da21b 100644 --- a/content/en/flux/use-cases/gh-actions-app-builder.md +++ b/content/en/flux/use-cases/gh-actions-app-builder.md @@ -5,6 +5,14 @@ description: "How to build and push image tags for Flux from Git branches and ta weight: 39 --- +{{% alert color="warning" title="Disclaimer" %}} +This document is under review and may be declared out of scope for Flux. + +Note that this guide needs further review in consideration of Flux v2.0.0. It also predates the introduction of `OCIRepository` and likely needs updates in consideration of those advancements. + +Expect this doc to either be archived soon, or to receive some overhaul. +{{% /alert %}} + This guide shows how to configure GitHub Actions to build an image for each new commit pushed on a branch, for PRs, or for tags in the most basic way that Flux's automation can work with and making some considerations for both dev and production. A single GitHub Actions workflow is presented with a few variations but one simple theme: Flux's only firm requirement for integrating with CI is for the CI to build and push an image. So this document shows how to do just that. @@ -118,7 +126,7 @@ An individual image tag name (string) has two parts, `IMAGE` which represents th Image tags can be mutable or immutable. Flux works best with immutable tags: `latest` and `canary` are examples of mutable tags. -This example produces both mutable and immutable tags because Flux works with immutable tags, but many users still expect a `latest` tag even if Flux won't use it. Mutable tags are useful for example with environment branches, to stably represent the latest build in a named environment, but they are contrary to GitOps, and Flux automation demands a timestamp or something sortable in the tag string. Thus mutable tags alone are not suitable for any Flux purpose. +This example produces both mutable and immutable tags because Flux works with immutable tags, but many users still expect a `latest` tag even if Flux won't be able to take advantage of it. Mutable tags are useful for example with environment branches, to stably represent the latest build in a named environment, but their use is generally contrary to GitOps principles. Flux automation demands immutable tags, with a timestamp or something else sortable in the tag string. Thus mutable tags alone are not suitable for most purposes in Flux. In this example, `LATEST_ID` represents a mutable tag and `latest` as a tag represents the last release build that was pushed from any Git tag. The `canary` tag is the last image that was pushed from any branch. diff --git a/content/en/flux/use-cases/gh-actions-auto-pr.md b/content/en/flux/use-cases/gh-actions-auto-pr.md index 277012de9..b06dbce83 100644 --- a/content/en/flux/use-cases/gh-actions-auto-pr.md +++ b/content/en/flux/use-cases/gh-actions-auto-pr.md @@ -5,6 +5,12 @@ description: "How to configure GitHub Pull Requests for Flux image updates." weight: 50 --- +{{% alert color="warning" title="Disclaimer" %}} +Note that this guide needs review in consideration of Flux v2.0.0, and likely needs to be refreshed. + +Expect this doc to either be archived soon, or to receive some overhaul. +{{% /alert %}} + This guide shows how to configure GitHub Actions to open a pull request whenever a selected branch is pushed. From [Image Update Guide] we saw that Flux can set `.spec.git.push.branch` to [Push updates to a different branch] than the one used for checkout. diff --git a/content/en/flux/use-cases/gh-actions-manifest-generation.md b/content/en/flux/use-cases/gh-actions-manifest-generation.md index a6c34332c..a88fd8ac7 100644 --- a/content/en/flux/use-cases/gh-actions-manifest-generation.md +++ b/content/en/flux/use-cases/gh-actions-manifest-generation.md @@ -5,6 +5,20 @@ description: "How to use GitHub Actions for Kubernetes manifest generation." weight: 40 --- +{{% alert color="warning" title="Disclaimer" %}} +This document is under review and may be declared out of scope for Flux. + +Note that this guide no longer describes the recommended way to handle manifest generation in Flux. It also predates the introduction of `OCIRepository` and needs updates in consideration of those advancements. + +Expect this doc to either be archived soon, or to receive a major overhaul in support of the new preferred approach described below. +{{% /alert %}} + +{{% alert color="info" title="Author's Note" %}} +If you want to use Flux with tooling-generated manifests today, you should capture the output and store it in an OCI Artifact with `flux push artifact`. The following doc uses an old method that has many disadvantages: it can't be provenance secured with Cosign. The artifacts can't be indexed as efficiently as an OCI registry's tag-based distribution. Nor can the delivery of a private Git repository be authenticated and authorized in a workload cluster, using any cloud-based IAM or ambient environmental credentials that are typically used to secure a private OCI registry. + +These methods were developed to bridge the gap for Flux users transitioning from Flux v1. The introduction of the `OCIRepository` since then, has nigh obsoleted the approach shown here. Please follow the OCI Cheatsheet guide to understand what is possible, and migrate your workflows to use Flux OCI! +{{% /alert %}} + This example implements "build-time" manifest generation on GitHub Actions. Third-party tools are used to generate YAML manifests in a CI job. The updated YAML are committed and pushed to Git, where `kustomize-controller` finally applies them. diff --git a/content/en/flux/use-cases/jenkins.md b/content/en/flux/use-cases/jenkins.md index 5a8c27dce..915df3804 100644 --- a/content/en/flux/use-cases/jenkins.md +++ b/content/en/flux/use-cases/jenkins.md @@ -5,6 +5,12 @@ description: "How to use Jenkins CI for building images together with Flux's ima weight: 50 --- +{{% alert color="warning" title="Disclaimer" %}} +Note that this guide has not been updated since more than a year ago, it does not address Kubernetes 1.24 or above, and needs to be refreshed. + +Expect this doc to either be archived soon, or to receive an overhaul. +{{% /alert %}} + This guide explains how to configure Flux with Jenkins, with the core ideas of [GitOps Principles] in mind. Let Jenkins handle CI (or Continuous Integration: image build and test, tagging and pushing), and let Flux handle CD (or Continuous Deployment) by making use of the Image Update Automation feature. ## Declarative Artifacts diff --git a/content/en/flux/use-cases/karmada.md b/content/en/flux/use-cases/karmada.md index 12f49d93d..3ac97d164 100644 --- a/content/en/flux/use-cases/karmada.md +++ b/content/en/flux/use-cases/karmada.md @@ -7,6 +7,10 @@ weight: 20 {{% alert color="warning" title="Disclaimer" %}} Note that this guide is not for doing GitOps, but for managing Helm releases for applications among multiple clusters. + +Also note that this guide needs review in consideration of Flux v2.0.0, and likely needs to be refreshed. + +Expect this doc to either be archived soon, or to receive some overhaul. {{% /alert %}} ## Background From 57187fba8789c2638677d01f406dba3ac40177a1 Mon Sep 17 00:00:00 2001 From: Kingdon Barrett Date: Mon, 17 Jul 2023 17:39:30 -0400 Subject: [PATCH 2/2] normalize to match other messages Signed-off-by: Kingdon Barrett --- content/en/flux/flux-e2e.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/flux-e2e.md b/content/en/flux/flux-e2e.md index 84d550f4c..f8d1f42c6 100644 --- a/content/en/flux/flux-e2e.md +++ b/content/en/flux/flux-e2e.md @@ -6,7 +6,7 @@ weight: 146 --- {{% alert color="warning" title="Disclaimer" %}} -Note that this guide has not been updated since more than a year ago, it does not address `OCIRepository`, and needs to be refreshed for Flux 2.0.0. +Note that this guide has not been updated since more than a year ago. It does not address `OCIRepository`, needs review in consideration of Flux v2.0.0, and likely needs to be refreshed. Expect this doc to receive an overhaul soon. {{% /alert %}}