/frontend-forge-fe-operations

name: frontend-forge-fe-operations
description: "Operate FrontendExtension (FE) resources in frontend-forge: create, update, rebuild, inspect package artifacts, download packages, publish, unpublish, delete, and debug package/publish controller behavior. Use this skill whenever the user mentions FE operations, FrontendExtension lifecycle, extension package/download/publish/unpublish, artifact ConfigMaps, package Jobs, publisher Jobs, publish target ConfigMaps or Secrets, rebuild-token, package-state/publish-state labels, or troubleshooting FE status in a Kubernetes cluster."

Frontend Forge FE Operations

When to use

Use this skill for operational work around `FrontendExtension` resources:

• Create or update an FE manifest
• Trigger or inspect package generation
• Force a rebuild with the rebuild-token annotation
• Download the generated package artifact
• Publish, unpublish, or delete an extension
• Inspect FE status, conditions, labels, Jobs, artifact ConfigMaps, and publish targets
• Debug FE package phases such as `Packaging`, `Ready`, and `Failed`, plus publish/unpublish phases such as `Pending`, `Running`, `Succeeded`, and `Failed`

If the task is about `FrontendIntegration` runtime `JSBundle` creation, use the FI operations skill instead. FE package/publish does not create a runtime `JSBundle` in the current cluster.

Quick Entry

• Create or update FE -> read `references/lifecycle.md`
• Rebuild package -> read `references/lifecycle.md`
• Publish, unpublish, delete-with-unpublish, list through API, or download -> read `references/api.md`
• Inspect package Job, artifact ConfigMap, publish Job, labels, or conditions -> read `references/inspection.md`
• Debug stuck or failed state -> read `references/inspection.md`, then check controller logs

Preconditions

• The current Kubernetes context is pointed at the target cluster.
• The FE CRD exists: `frontendextensions.frontend-forge.kubesphere.io`.
• The FE controller is installed, usually as the `extension-controller` component.
• The FE API is installed when using download, publish, unpublish, or delete-with-unpublish HTTP operations.
• The build service configured by `BUILD_SERVICE_BASE_URL` is reachable from package Jobs.
• Publish target data exists when publishing, normally `ConfigMap/ksbuilder-publish-config` in `extension-frontend-forge`.

Source of truth

Prefer live cluster state for operations and repo docs for expected behavior:

• `kubectl get fe <name> -o yaml`
• `kubectl get jobs -n <work-namespace> -l frontend-forge.kubesphere.io/fe-name=<name>`
• `spec/frontend-extension-design.md`
• `spec/crds.md`
• `spec/k8s-resources.md`
• `config/samples/frontendextension-inspecttask.yaml`
• `crates/api/src/fe.rs`
• `crates/frontend-extension-controller`
• `crates/frontend-forge-extension-api`

Resource Model

• `FrontendExtension`
• cluster-scoped
• short name: `fe`
• source object for package, artifact, download, publish, and unpublish state
• Package Job
• namespaced
• default namespace: `extension-frontend-forge`
• typical name: `fe-<fe-name>-package-<artifact-key-12>-a<attempt>`
• Artifact ConfigMap
• namespaced
• default namespace: `extension-frontend-forge`
• referenced by `status.artifact.storage.ref`
• contains `binaryData["package.tgz"]`, `data["artifact.json"]`, and `data["files.json"]`
• Publish or unpublish Job
• namespaced
• default namespace: `extension-frontend-forge`
• typical names:
• `fe-<fe-name>-publish-<request-id-hash-short>`
• `fe-<fe-name>-unpublish-<request-id-hash-short>`
• Publish target
• `ConfigMap` or `Secret`
• default chart target is usually `ConfigMap/ksbuilder-publish-config` in the release namespace

Default names and namespaces can change through Helm values and controller environment variables. Use FE status, Job labels, and controller deployment env vars before assuming defaults.

Common Commands

Inspect FE:

kubectl get fe <name> -o yaml
kubectl get fe <name> -o jsonpath='{.status}{"\n"}'
kubectl get fe <name> -o jsonpath='{.status.phase}{" "}{.status.publish.phase}{" "}{.status.unpublish.phase}{"\n"}'
kubectl get fe -l frontend-forge.kubesphere.io/package-state=ready
kubectl get fe -l frontend-forge.kubesphere.io/publish-state=published

Create or update:

kubectl apply -f <file.yaml>
kubectl apply -f config/samples/frontendextension-inspecttask.yaml

Find package Job and logs:

kubectl get fe <name> -o jsonpath='{.status.packageJob.namespace}{" "}{.status.packageJob.name}{"\n"}'
kubectl -n <job-namespace> get job <job-name> -o yaml
kubectl -n <job-namespace> logs job/<job-name>

Find artifact ConfigMap:

kubectl get fe <name> -o jsonpath='{.status.artifact.storage.ref.namespace}{" "}{.status.artifact.storage.ref.name}{" "}{.status.artifact.storage.key}{"\n"}'
kubectl -n <artifact-namespace> get cm <artifact-configmap-name> -o yaml

Force a rebuild:

kubectl annotate fe <name> frontend-forge.kubesphere.io/rebuild-token="$(date +%s)" --overwrite

Inspect publish or unpublish Jobs:

kubectl get jobs -n extension-frontend-forge -l frontend-forge.kubesphere.io/fe-name=<name>
kubectl get fe <name> -o jsonpath='{.status.publish.jobRef.namespace}{" "}{.status.publish.jobRef.name}{"\n"}'
kubectl get fe <name> -o jsonpath='{.status.unpublish.jobRef.namespace}{" "}{.status.unpublish.jobRef.name}{"\n"}'
kubectl -n <job-namespace> logs job/<job-name>

FE API operations:

KS_API=https://<kubesphere-host>
FE_API="$KS_API/kapis/frontend-forge-api.kubesphere.io/v1alpha1/frontendextensions"
curl -fS "$FE_API/<name>"
curl -fS -u "user:password" "$FE_API/<name>"  # user runs this if /kapis returns 401/403
curl -fS "$FE_API/<name>/publish"      # read publish status only
curl -fS -X POST -H 'Content-Type: application/json' --data '{"requestId":"manual-1","expectedArtifactDigest":"sha256:<digest>"}' "$FE_API/<name>/publish"
curl -fS "$FE_API/<name>/unpublish"    # rea