Merge pull request #1564 from fluxcd/mark-stale-docs

Mark some use-cases docs stale

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`, needs review in consideration of Flux v2.0.0, and likely needs to be refreshed.
+
+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

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.
 

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.

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.

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

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