From ba87b2ad0fe74198db11b5eba85d0582c797ceee Mon Sep 17 00:00:00 2001
From: Stefan Prodan <stefan.prodan@gmail.com>
Date: Wed, 3 Sep 2025 23:46:16 +0300
Subject: [PATCH] Add ExternalArtifact API documentation

Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
---
 docs/spec/v1/externalartifacts.md | 114 ++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 docs/spec/v1/externalartifacts.md

diff --git a/docs/spec/v1/externalartifacts.md b/docs/spec/v1/externalartifacts.md
new file mode 100644
index 00000000..1eccbe0e
--- /dev/null
+++ b/docs/spec/v1/externalartifacts.md
@@ -0,0 +1,114 @@
+# External Artifacts
+
+<!-- menuweight:100 -->
+
+The `ExternalArtifact` is a generic API designed for interoperability with Flux.
+It allows 3rd party controllers to produce and store [Artifact](#artifact) objects
+in the same way as Flux's own source-controller.
+For more details on the design and motivation behind this API,
+see [RFC-0012](https://github.com/fluxcd/flux2/tree/main/rfcs/0012-external-artifact).
+
+## Example
+
+The following is an example of a ExternalArtifact produced by a 3rd party
+source controller:
+
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: ExternalArtifact
+metadata:
+  name: my-artifact
+  namespace: flux-system
+spec:
+  sourceRef:
+    apiVersion: example.com/v1
+    kind: Source
+    name: my-source
+status:
+  artifact:
+    digest: sha256:35d47c9db0eee6ffe08a404dfb416bee31b2b79eabc3f2eb26749163ce487f52
+    lastUpdateTime: "2025-08-21T13:37:31Z"
+    path: source/flux-system/my-source/35d47c9d.tar.gz
+    revision: v1.0.0@sha256:35d47c9db0eee6ffe08a404dfb416bee31b2b79eabc3f2eb26749163ce487f52
+    size: 20914
+    url: http://example-controller.flux-system.svc.cluster.local./source/flux-system/my-source/35d47c9d.tar.gz
+  conditions:
+    - lastTransitionTime: "2025-08-21T13:37:31Z"
+      message: stored artifact for revision v1.0.0
+      observedGeneration: 1
+      reason: Succeeded
+      status: "True"
+      type: Ready
+```
+
+## ExternalArtifact spec
+
+### Source reference
+
+The `spec.sourceRef` field is optional and contains a reference
+to the custom resource that the ExternalArtifact is based on.
+
+The `spec.sourceRef` contains the following fields:
+
+- `apiVersion`: the API version of the custom resource.
+- `kind`: the kind of the custom resource.
+- `name`: the name of the custom resource.
+- `namespace`: the namespace of the custom resource. If omitted, it defaults to the
+  namespace of the ExternalArtifact.
+
+## ExternalArtifact status
+
+### Artifact
+
+The ExternalArtifact reports the latest synchronized state
+as an Artifact object in the `.status.artifact`.
+
+The `.status.artifact` contains the following fields:
+
+- `digest`: The checksum of the tar.gz file in the format `<algorithm>:<checksum>`.
+- `lastUpdateTime`: Timestamp of the last artifact update.
+- `path`: Relative file path of the artifact in storage.
+- `revision`: Human-readable identifier with version and checksum in the format `<human-readable-identifier>@<algorithm>:<checksum>`.
+- `size`: Number of bytes in the tar.gz file.
+- `url`: In-cluster HTTP address for artifact retrieval.
+
+### Conditions
+
+The ExternalArtifact reports its status using Kubernetes standard conditions.
+
+#### Ready ExternalArtifact
+
+When the 3rd party controller has successfully produced and stored an
+Artifact in storage, it sets a Condition with the following
+attributes in the ExternalArtifact's `.status.conditions`:
+
+- `type: Ready`
+- `status: "True"`
+- `reason: Succeeded`
+
+The `message` field should contain a human-readable message indicating
+the successful storage of the artifact and the associated revision.
+
+If the 3rd party controller performs a signature verification
+of the artifact, and the verification is successful, a Condition with the
+following attributes is added to the ExternalArtifact's `.status.conditions`:
+
+- `type: SourceVerified`
+- `status: "True"`
+- `reason: Succeeded`
+
+The `message` field should contain a human-readable message indicating
+the successful verification of the artifact and the associated verification method.
+
+#### Failed ExternalArtifact
+
+If the 3rd party controller fails to produce and store an Artifact,
+it sets the `Ready` Condition status to `False`, and adds a Condition with
+the following attributes to the ExternalArtifact's `.status.conditions`:
+
+- `type: Ready`
+- `status: "False"`
+- `reason: FetchFailed` | `reason: StorageOperationFailed` | `reason: VerificationFailed`
+
+The `message` field should contain a human-readable message indicating
+the reason for the failure.