diff --git a/docs/en/solutions/Alauda_DevOps_Best_Practices_Overview.md b/docs/en/solutions/Alauda_DevOps_Best_Practices_Overview.md deleted file mode 100644 index 398e07468..000000000 --- a/docs/en/solutions/Alauda_DevOps_Best_Practices_Overview.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -products: - - Alauda Container Platform - - Alauda DevOps -kind: - - Article -ProductsVersion: - - 4.x -id: KB261000020 ---- - -# Alauda DevOps Best Practices: Overview and Scenario Guide - -This series helps application and platform teams combine Alauda DevOps capabilities into a delivery workflow. Start with a working pipeline, connect build outputs to controlled releases, and then standardize the platform for multiple isolated projects. - -The configuration baseline is Alauda DevOps Pipelines 4.15, Artifact Hub Shim 1.0, Connectors 1.14, and Alauda Container Platform GitOps 4.4 on a compatible ACP installation. Use the compatibility requirements of each component when selecting packages. Examples use GitLab, Harbor, Nexus, and SonarQube. They describe a reference implementation, with environment preparation and acceptance checks required before production use. - -The series has three entry points: - -| Your starting point | Read next | -| --- | --- | -| You need a build or test pipeline for one repository. | [Start a pipeline](#start-a-pipeline) below. | -| A pipeline already runs; you need a traceable path from a commit to production. | [From Commit to Production on ACP](./From_Commit_to_Production_on_ACP.md). | -| You operate a shared platform and need repeatable configuration and project onboarding. | [Managing Platform Configuration and Onboarding Isolated Projects](./Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md). | - -The [companion samples](https://github.com/AlaudaDevops/devops-best-practices-samples) contain the platform repository, project declaration, onboarding pipelines, GitOps repository template, application delivery examples, and acceptance scripts. Replace example addresses, image references, identities, and encrypted credential placeholders before using them. - -## The overall design - -The delivery layer moves one change from source to an immutable image and then to an environment. The platform layer supplies reusable definitions, tool access, namespaces, and operating settings. The control layer decides what may run, who approves a release, and what evidence must be retained. - -```mermaid -flowchart TB - subgraph Controls[Control layer] - Policy[Pipeline and image admission] - Approval[Release approval] - Audit[Run and log retention] - end - subgraph Delivery[Delivery layer] - Source[Source repository] --> Trigger[PaC or Triggers] - Trigger --> Build[Build and scan] - Build --> Image[Image identified by digest] - Image --> Test[Test deployment] - Test --> Promote[Promote the selected digest] - Promote --> Production[Production GitOps change] - end - subgraph Platform[Platform layer] - Catalog[Versioned catalog pipelines and tasks] - Connectors[Project and administrator Connectors] - Git[Platform configuration and project declarations] - end - Policy -.-> Trigger - Policy -.-> Production - Approval -.-> Promote - Audit -.-> Build - Catalog -.-> Build - Connectors -.-> Build - Git -.-> Connectors -``` - -Application developers own source and application delivery configuration. Platform administrators own shared components, admission rules, administrator credentials, and onboarding. Release approvers authorize a selected digest after examining its build and test evidence. Separate the release identity from the build identity. - -## Start a pipeline - -Choose the simplest definition model that meets the team's needs. The models can coexist. - -| Model | Definition and trigger | Use it when | -| --- | --- | --- | -| Pipeline in the cluster | Create a Pipeline in a project namespace. Save parameters, Workspaces, and Integrations in a Run Template. Start manually, through Triggers, or on a schedule. | A small number of pipelines need a straightforward execution entry. | -| Pipelines as Code (PaC) | Keep PipelineRun definitions in the application's `.tekton/` directory. Code events start runs and report results to the merge request. | Definitions should evolve with source and participate in merge-request checks. | -| Centrally managed template | Maintain a versioned Pipeline in the catalog, or a Pipeline in a controlled namespace. Projects supply parameters through a Run Template or a PaC PipelineRun using a resolver. | Multiple projects should share the same standard workflow. | - -For PaC retries, use `/test ` in the merge request and refer to [Trigger PAC Pipelines](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/trigger_pipeline.html) for the complete syntax. Use one event route for each event: PaC or Triggers. Enabling both routes for the same event can start duplicate work. - -Start with [Run Template](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/run_template.html), [Configure GitLab Repository](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/guides/configure_gitlab_repo.html), or [Centralized Management with Hub Pipeline and Run Template](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/hub_pipeline_run_template_centralized_management.html). The [Application CI/CD tutorials](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/tutorials/index.html) provide a guided implementation. - -## Connect the delivery stages - -| Requirement | Recommended combination | Detailed guidance | -| --- | --- | --- | -| Build a traceable artifact | Reuse catalog Tasks, scan the output, and pass its digest to later stages. | [From Commit to Production](./From_Commit_to_Production_on_ACP.md). | -| Deploy to development or test | Update the workload by digest directly when Git history of environment state is unnecessary. | [Application CI/CD tutorials](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/tutorials/index.html). | -| Deploy to production | Review a change to the production GitOps repository; Argo CD reconciles the selected digest. | [Alauda Container Platform GitOps](https://docs.alauda.io/gitops/4.4/). | -| Separate production artifact access | Approve and copy the selected image by digest into a production registry project. | [Promote Artifacts with Skopeo Copy](https://docs.alauda.io/alauda-devops-artifacthub-shim/1.0/catalog/how_to/promote_artifacts_with_skopeo_copy.html). | -| Record who approved a release | Add an ApprovalTask, use group resource names, and retain its approval response. | [Manual Approval Gate](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/manual_approval_gate.html). | -| Verify image signatures | Configure Chains keys and registry access centrally; verify the image by digest before promotion and at deployment admission. | [Signing Key Configuration](https://docs.alauda.io/alauda-devops-pipelines/4.15/chains/configure/signing_key_configuration.html). | -| Hand off an artifact event | Map a Harbor event to the next pipeline, carrying the digest. Check scan and signing evidence separately. | [Use Harbor Event Triggers](https://docs.alauda.io/alauda-devops-pipelines/4.15/triggers/how_to/harbor_events.html). | - -Promotion copies a selected image; it does not establish that the image passed CI. The approver must match the digest with a successful trusted build and the test environment. Signatures establish the configured signer's statement; their meaning also depends on control over the signing key and the definitions allowed to run. - -The samples deliberately keep test CD, promotion, and production CD as manually started runs. Their inputs come from the preceding run's digest result. Harbor-driven automation is a separate integration step. The release tutorial's first deployment is performed by an administrator; subsequent releases follow the configured delivery path. - -## Prepare a shared platform - -Platform settings are administrator decisions. Roll them out in stages and check [Feature Maturity](https://docs.alauda.io/alauda-devops-pipelines/4.15/overview/feature_maturity.html) for the selected release. - -| Platform concern | Recommended approach | -| --- | --- | -| Tool access | Use project-scoped Connectors. Proxy access uses short-lived workload tokens. Manage image pull Secrets, PaC clone credentials, and Chains registry credentials as separate long-lived credential responsibilities. | -| Project onboarding | Orchestrate the four Connectors automatic creation Tasks, then seed a project GitOps repository and propose platform registration through a merge request. Complete the administrator prerequisites and acceptance checks. | -| Platform configuration | Keep component settings, policies, encrypted administrator credentials, and project declarations in a platform repository. Assign one owner to each resource or field. | -| Namespace isolation | Use separate project namespaces and tool-side tenants. Separate build, delivery, and workload namespaces and restrict access to administrator namespaces. | -| Execution policy | Use platform ClusterPolicies and project Policies. Restrict direct TaskRun and CustomRun creation. Optionally require approved resolver types and coordinates. Move from Audit to Enforce after checking intended workflows. | -| Cleanup | Select one cleanup mechanism. For event-based Pruner, review global defaults and namespace override settings before enabling deletion. | -| Audit history | Store run records and logs in external Results storage with an explicit retention period. Export approval evidence separately before deleting its objects. | -| Scheduled work | Use ScheduledTrigger or CronJob for reconciliation and rotation, with failure alerts and no overlapping runs for a tenant. | - -Results Watcher scope deserves a separate rollout decision. Its default watch scope can affect finished runs across the cluster and add `results.tekton.dev/*` finalizers. Scope it before enabling it. Disabling archiving does not remove existing finalizers; follow the product recovery procedure before cleanup. After Pruner removes cluster objects, the external Results store is the audit source. - -The [platform article](./Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md) explains the 18 platform decisions, repository layout, ownership boundaries, onboarding workflow, rotation, and acceptance checks. - -## Operate without internet access - -Make the catalog, pinned tool and base images, package dependencies, certificates, and vulnerability databases available through the platform's approved internal services. Runtime pipelines must resolve Tasks and Pipelines from local catalog or cluster sources. The sample CI configuration points Trivy at `registry.example.com/mirror/trivy-db:2`; replace it with a reachable database mirror and grant the scanner access. - -The degree of network isolation, number of teams, and required approval evidence are deployment inputs that the platform team must decide. Capacity sizing, migration and decommissioning automation, platform disaster recovery, customer change-management integration, and offline package distribution procedures are outside this series. Define those procedures for the target environment. - -## Related information - -- [Pipelines 4.15](https://docs.alauda.io/alauda-devops-pipelines/4.15/) -- [Artifact Hub Shim 1.0](https://docs.alauda.io/alauda-devops-artifacthub-shim/1.0/) -- [Connectors 1.14](https://docs.alauda.io/alauda-devops-connectors/1.14/) -- [GitOps 4.4](https://docs.alauda.io/gitops/4.4/) -- [Software Supply Chain Security with Tekton and Kyverno](./Software_Supply_Chain_Security_of_Alauda_Container_Platform_with_Tekton_and_Kyverno.md) -- [Pipeline Policy Constraints with Tekton and Kyverno](./Pipeline_Policy_Constraints_with_Tekton_and_Kyverno.md) diff --git a/docs/en/solutions/From_Commit_to_Production_on_ACP.md b/docs/en/solutions/From_Commit_to_Production_on_ACP.md deleted file mode 100644 index 883d6d63d..000000000 --- a/docs/en/solutions/From_Commit_to_Production_on_ACP.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -products: - - Alauda Container Platform - - Alauda DevOps -kind: - - Article -ProductsVersion: - - 4.x -id: KB261000023 ---- - -# From Commit to Production on ACP: Choosing Triggers, Deployment, and Release Controls - -Use this article to choose where pipeline definitions live, how deployments consume build outputs, and where approvals, promotion, and signature checks belong. For a guided implementation, follow the [Application CI/CD tutorials](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/tutorials/index.html). - -This is the delivery part of [Alauda DevOps Best Practices](./Alauda_DevOps_Best_Practices_Overview.md). Its configuration baseline is Pipelines 4.15, Artifact Hub Shim 1.0, Connectors 1.14, and GitOps 4.4. Project namespaces, tool-side resources, and Connectors must already exist; the [platform article](./Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md) explains their preparation. - -The [companion samples](https://github.com/AlaudaDevops/devops-best-practices-samples) use a fictional `shop` project. CI runs in `shop-build`; CD and promotion run in `shop-cd`; workloads run in `shop-test` and `shop-prod`. Replace every example address, tool image, group, credential placeholder, and policy identity for your environment. Make the vulnerability database, tool images, base images, and dependencies available locally for disconnected execution. - -## Follow one image identity through the workflow - -```mermaid -flowchart LR - Commit[Merge application change] --> CI[Build and scan] - CI --> Source[Source registry image by digest] - Source --> Test[Deploy and verify in test] - Test --> Approve[Approve selected digest] - Approve --> Copy[Copy image to production registry] - Copy --> Sign[Verify signature and provenance] - Sign --> MR[Review production GitOps change] - MR --> Sync[Argo CD sync and rollout] -``` - -Use `repository@sha256:` for deployment, promotion sources, signature verification, and audit correlation. Tags help people identify releases; a tag alone does not identify immutable content. A Harbor push event establishes that an image was pushed. It does not establish successful scanning, testing, signing, or approval. - -When a vulnerability is found in an already deployed image, fix it and use the same build, promotion, and deployment workflow to release a new digest. Keep the build evidence and the decision to replace the vulnerable image with the release record. - -## Choose where definitions live and how runs start - -| Model | Definition location | Trigger | Suitable use | -| --- | --- | --- | --- | -| Cluster Pipeline | Pipeline in the project namespace; execution settings in a Run Template | Manual, Triggers, or ScheduledTrigger | A small number of centrally operated pipelines | -| Pipelines as Code | PipelineRun files in the application's `.tekton/` directory | Push and merge-request events | Definitions versioned with source and merge-request checks | -| Central template | Versioned catalog Pipeline, or a Pipeline in a controlled cluster namespace | Run Template or a PaC PipelineRun with `pipelineRef` | Shared standards across projects | - -Start with a cluster Pipeline when that is sufficient. Add PaC when the change history and merge-request experience matter. Use central templates when projects should reuse a standard workflow. The same project can use all three for different jobs. Choose one route, PaC or Triggers, for a given event. - -For retries from a merge request, use `/test `. Keep the complete syntax in one place by linking to [Trigger PAC Pipelines](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/trigger_pipeline.html). - -### Combine PaC with a central template - -Keep event annotations and project inputs in `.tekton/`. Reference the platform's Pipeline with a resolver and a pinned version. The following fragment shows the reference used by the application sample; it is not a complete PipelineRun. Use the sample's full parameter and Workspace bindings. - -```yaml -spec: - pipelineRef: - resolver: hub - params: - - name: catalog - value: catalog-pipelines - - name: kind - value: pipeline - - name: name - value: python-image-build-scan-deploy - - name: version - value: "0.3" -``` - -Use `resolver: cluster` for a controlled cluster Pipeline. Avoid a bare `pipelineRef.name` in PaC definitions when admission must inspect the definition's source. See [Resolvers](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/concepts/resolver_concept.html) and [Define PipelineRuns in Git](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/maintain_pipeline_code.html). - -Upgrade a catalog Pipeline by reviewing a change to its pinned version. Projects do not automatically adopt a newly published version. For reproducible rollback of the definition, retain reviewed versions and define whether published coordinates are immutable. A Run Template's version change is a change to that existing template, rather than a reason to create another template. - -### Protect the definition and its runtime credentials - -For a self-managed GitLab instance, set `spec.git_provider.url` on every PaC `Repository`. Without that URL, the PaC behavior described in [Advanced Repository Configuration](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/advanced_repository_config.html) can send completion status requests and the Repository token to `gitlab.com`. Set the provider URL explicitly for application, platform, and project GitOps repositories. - -Set `spec.settings.pipelinerun_provenance: default_branch` where pre-merge runs must use reviewed definitions. This selects the definition, not trusted application code: a merge-request run still builds the proposed source with the credentials mounted by that definition. Limit those credentials and keep merge-request image outputs separate from release candidates. - -The sample separates the two outputs: - -| Definition | Event | Image repository | Delivery use | -| --- | --- | --- | --- | -| `sample-app/.tekton/ci.yaml` | Push to `main` | `registry.example.com/shop/hello` | Source for test CD and promotion | -| `sample-app/.tekton/ci-merge-request.yaml` | Merge request | `registry.example.com/shop/hello-mr` | Temporary merge-request artifacts | - -The sample's Harbor Connector has project-level access. Separating repository names does not itself enforce a credential boundary. For stronger separation, use a distinct temporary registry project and a credential that cannot write release-candidate images. Before delivery, check that the selected digest is the `IMAGE_DIGEST` of a successful trusted `main` CI run. - -Both sample CI definitions bind the Connector proxy CA through the `ca-bundle` Workspace. The proxy's CA is required even when the upstream registry uses a publicly trusted certificate. For offline scanning, set `trivyExtraArgs` to use the platform's mirrored vulnerability database, for example `--db-repository registry.example.com/mirror/trivy-db:2`. The scanner must be able to pull that image. - -The platform and GitOps repository validation samples compose `git-clone` and `run-script` inline. If the platform enables a policy that forbids inline `pipelineSpec`, publish that validation flow as a catalog Pipeline and reference it through a resolver. - -## Choose a deployment route per environment - -| Route | How the selected digest reaches the environment | Tradeoff | -| --- | --- | --- | -| Direct deployment | A task such as `workload-apply`, `helm-upgrade`, or `run-script` updates the workload. | Fewer moving parts; Git does not hold a second copy of environment state. | -| GitOps | A change updates the environment's image reference in Git; Argo CD reconciles it. | Reviewable environment state and history; requires a repository and a sync path. | - -A useful starting point is direct deployment for development or test and GitOps for production. The samples use GitOps for both test and production so that the same reconciliation path can be used in both environments. - -For direct deployment, use a digest in `workloadContainers`; use a lowercase `workloadKind`, such as `deployment`. The run identity needs access to read and update the target workload. Consult the catalog Task for its rollout, timeout, rollback, and cross-cluster options. - -For GitOps, use one directory and one Application per environment. Keep each image digest in one place, such as the Kustomize `images` entry: - -```text -gitops/ -├── base/ -└── envs/ - ├── test/kustomization.yaml - └── prod/kustomization.yaml -``` - -In the sample, test CD uses `submitMode: direct`; production CD uses `submitMode: pr`. The production overlay is seeded with the production registry repository, so a release changes only its digest. The first production deployment waits for a promoted image. - -Enforce production Git review in the code platform. Use protected branches and, where supported, code-owner approval. Other options include a separately protected production branch or repository, or a reviewed server-side policy. Branch protection alone does not create directory-level protection. Remove direct production write access that would bypass the chosen review path. - -### Pass results between build, promotion, and GitOps - -`gitops-repo-update` is a Pipeline and runs as a separate PipelineRun. Pass the selected digest as an argument to its update script. Use a fresh source Workspace volume per run and an image that contains every command used by the script. `submitMode: pr` also requires the configured GitLab CLI image and a token with API access. - -The sample updates the `digest:` line with `sed` and verifies the rendered image with Kustomize. This preserves a one-line production diff. Avoid using a rewrite operation that changes unrelated formatting or image fields. The GitOps writer token needs the scopes required for cloning, pushing, and creating the merge request; keep it separate from the application CI token. - -The sample starts test CD, promotion, and production CD manually from rendered PipelineRun YAML. Replace the template parameters, verify the image mapping, identity, and Workspaces, and submit with `kubectl create`. Use [Run Template](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/run_template.html) for other execution entries. Harbor event automation is an additional integration, not part of the sample's manual path. - -Production rollback follows the same review boundary: select a retained, previously promoted digest, verify its signature and application compatibility, and review the GitOps change. Database and data migrations need an application-specific rollback plan. Establish and rehearse the complete rollback runbook in the target environment. Configure [Harbor tag retention](https://goharbor.io/docs/2.14.0/working-with-projects/working-with-images/create-tag-retention-rules/) and [tag immutability](https://goharbor.io/docs/2.14.0/working-with-projects/working-with-images/create-tag-immutability-rules/) so that required rollback images remain available. - -## Select the release controls - -Promotion, approval, credential gating, and image admission solve separate decisions: - -| Decision | Recommended control | -| --- | --- | -| Should production use a separate artifact project? | Copy the selected digest into that project, then update the production Git reference. | -| Who authorizes the selected release? | An ApprovalTask, a production Git merge-request review, or both, according to policy. | -| Who may use the production Connector? | A dedicated release identity plus admission and RBAC restrictions. Add approval-gated proxy access when credential owners and pipeline owners are separate. | -| What may be deployed? | Admission policies for allowed production repositories, signatures, and any required approved-digest evidence. | - -Use the Core promotion admission rules in [Constrain Artifact Promotion with Kyverno](https://docs.alauda.io/alauda-devops-artifacthub-shim/1.0/catalog/how_to/constrain_artifact_promotion_with_kyverno.html). Rules 1–3 constrain the promotion execution path. Add rule 4 when the promotion Pipeline is maintained in a namespace, to control changes to that definition. The companion samples do not install these promotion rules or a production-repository-only deployment policy; platform administrators must add them before using the reference design as a production control. - -Promotion validates the source and destination mapping and copies bytes. It does not query CI to establish that the image passed. The approver must correlate the digest with the trusted build, scan, and test evidence. The sample validates that the image mapping is first, the source uses a SHA-256 digest, and the repositories and release-label format match the configured workflow. Optional signature mappings must refer to the same image digest. - -### Add an approval node - -Use ACP group resource names in `approvers`, rather than a group's display name or an individual's name. The following is a task fragment; replace the example group with the actual resource name: - -```yaml -- name: wait-for-approval - taskRef: - apiVersion: openshift-pipelines.org/v1alpha1 - kind: ApprovalTask - timeout: "24h" - params: - - name: approvers - value: - - group:release-managers - - name: numberOfApprovalsRequired - value: "1" - - name: description - value: "Approve promotion into production" -``` - -PipelineRun and task timeout budgets must include work before approval, the entire approval window, and work after approval. Keep the approver group separate from identities allowed to initiate or modify release runs. Use [Manual Approval Gate](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/manual_approval_gate.html) for approval permissions, group responses, and timeout configuration. Retain the ApprovalTask responses separately before the objects are removed. - -Approvers can inspect pending work in the console or through `kubectl`. The optional sample `promotion/optional/console-approver.yaml` supplies a custom console role and group binding; review its scope before applying it. An approval notification can be sent with the catalog's `send-mail` Task. Email addresses, SMTP configuration, and credentials must be configured separately; the sample does not integrate that notification step. - -Customer change-management system integration is outside this series. The available building blocks are the approval node and [Incoming Webhooks](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/incoming_webhooks.html). Define the mapping and audit contract for that integration separately. - -### Gate the production Connector after approval - -Keep the production Connector and its Secret in a namespace where project members cannot create Pods or run arbitrary pipelines. A Pod can mount a Secret from its own namespace without a separate Secret-read authorization check. Consequently, permission to create Pods or PipelineRuns in a credential-bearing namespace is a credential boundary. - -The sample release ServiceAccount `shop-release` reads the source Connector and mounts the production Connector from `platform-connectors`. Its standing grants are in `sample-app/promotion/standing-access.yaml`. Use RBAC for the cross-namespace proxy grants described by the product guide. - -Approval gating uses two installation-wide feature flags. Roll them out in this order: - -1. Inventory every identity mounting a Connector that is not behind approval. Prepare its read authorization and `connectors/proxy` permission with verb `*`. A `get` grant on `connectors/proxy` is insufficient. Do not grant direct proxy access to the production Connector that approval must gate. -2. Enable `enable-connectors-approval`. Immediately create the required AccessPolicies, including the administrator-Connector grants and the production approval policy. Do not start affected runs in the interval between enabling the flag and creating the policies. -3. In the production AccessPolicy, configure the designated `approvers` and keep them aligned with the ApprovalTask and promotion admission policy. Remove any other matching default or direct proxy grants. -4. Enable `enable-connector-proxy-permissions`, which applies the proxy permission check to requests as well. - -Set feature flags through `ConnectorsConfig`. For the full configuration and verification path, see [Enable Proxy Permission Checks and Approval Gating](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors/how_to/enable_proxy_permissions_and_approval.html), [AccessPolicy](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors/concepts/access_policy.html), and [Skopeo Copy connector approval](https://docs.alauda.io/alauda-devops-artifacthub-shim/1.0/catalog/how_to/promote_artifacts_with_skopeo_copy.html#connector-approval). - -`defaultPermission` policies have authorization prerequisites and are not a substitute for every cross-namespace RBAC grant. A Ready policy alone does not establish a working mount. Verify the actual identity, Pod events, mounted configuration, and AccessRequest result. - -## Sign and verify the image - -Configure Chains signing keys centrally and distribute only the public verification key to projects. Protect both the signing Secret and the ability to create Pods in its namespace. Application teams do not need access to the signing Secret. - -The sample stores signatures and attestations beside the image. Chains first uses matching registry credentials from the run's ServiceAccount. Those credentials must be able to push to the image's registry project. Where they are absent, configure a centrally managed registry credential on the Chains controller through `TektonConfig`. Chains does not use a Connector's CSI proxy Workspace as its registry credential. - -The central credential is created by an administrator, outside Git. Limit it to the registry projects that Chains must read and sign. When onboarding a project, the platform team must add its source and production registry projects to that credential's access. Rotate it and restrict its Secret and namespace. Apply controller configuration changes in a maintenance window, preserving other container options already configured. - -A successful PipelineRun is not proof of stored signatures. Inspect TaskRun signing annotations and events, and independently verify the image and its attestation. The acceptance object here is the image digest and the copy TaskRun's provenance; approval history is separate evidence. - -```bash -# IMAGE is the selected repository@sha256:digest; the platform supplies cosign.pub. -cosign verify --key cosign.pub "$IMAGE" -cosign verify-attestation --key cosign.pub --type slsaprovenance "$IMAGE" -``` - -For an offline installation configured without a transparency log, use the product's offline verification settings, including `--insecure-ignore-tlog=true` where required. This skips the external transparency-log check; retain the signature and attestation checks. Authenticate to private registries without committing the login credentials. - -If the platform chooses a separate signature repository, configure `storage.oci.repository` centrally and use the corresponding `COSIGN_REPOSITORY` in verification and the repository setting in Kyverno. Review storage and overwrite behavior before combining build and promotion attestations for the same digest. Copying build signature attachments during promotion is optional; use the documented `imageMappings` and `multiArch: all` configuration if selected. - -At deployment admission, start the image-verification policy in Audit, with the sample's `mutateDigest: false` setting, and review the matching images and reports before Enforce. The sample's production image list is explicit: add each newly onboarded production repository to the policy. See [Image Signature Verification](https://docs.alauda.io/alauda-devops-pipelines/4.15/chains/how_to/image_signature_verification.html). - -## Check the controls at their actual enforcement points - -| Point in the workflow | What is checked | Remaining responsibility | -| --- | --- | --- | -| Repository event and definition resolution | Event matching and reviewed definition source | Limit the credentials available to proposed source code. | -| PipelineRun admission | Allowed definition source and configured promotion path | Restrict who can edit referenced definitions and parameters. | -| TaskRun or CustomRun creation | Approved controller identities for direct-run restrictions | Protect automation identities and their RBAC. | -| Approval | Designated approver responses | Match the approved digest with CI and test evidence. | -| Production registry write | Promotion mapping and credential access | Control other writers, including the signing identity. | -| Workload admission | Allowed registry and required signature checks | Remove direct deployment paths that bypass the policy. | -| Retention and cleanup | Selected run/log retention | Export approval evidence and verify archived access. | - -Use platform ClusterPolicies for the baseline and project Policies for additional restrictions. Restrict PolicyException creation or disable exceptions according to platform policy. A resolver-type allow-list alone does not pin catalog, repository, namespace, version, or definition content. The inline validation exception must be handled explicitly when enabling a no-inline policy. - -## Accept the delivery workflow - -Run `acceptance/01-commit-to-production.sh` from the sample only in an isolated acceptance project after replacing its inputs. The checks are an execution procedure, not a claim that an arbitrary environment is ready. - -| Check | Required evidence | -| --- | --- | -| CI completed | The trusted `main` run succeeded; its image repository and digest match the selected release input. | -| Test ran the selected image | Compare the complete workload image reference and verify rollout completion. | -| Promotion copied that image | The promotion result reports the expected destination repository and digest. | -| Production uses the promotion result | The GitOps merge request is merged, the rendered image matches the destination digest, and the workload rollout completed. `Synced` alone can describe an older revision. | -| Signature and provenance exist | Both cosign commands succeed against the production image. A signing annotation alone is insufficient. | -| Admission enforces the selected policy | Use a restricted-compatible probe in the acceptance project and distinguish policy rejection from Pod Security or image-pull failure. Clean up the probe afterward. | -| Approval is attributable | Save the ApprovalTask response, approver group members, selected digest, and related run identifiers in the release record. | - -Before production, address the sample's explicit hardening work: restrict the GitOps writer's namespace, protect production Git changes, install the promotion Core rules, constrain production image sources, and limit direct cluster writes. Do not grant project members Pod creation in namespaces that contain administrator or release credentials. Establish local rollback and policy-service recovery runbooks. - -Continue with [Managing Platform Configuration and Onboarding Isolated Projects](./Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md) for the platform configuration, project declarations, and operating boundaries behind this workflow. diff --git a/docs/en/solutions/Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md b/docs/en/solutions/Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md deleted file mode 100644 index d0d5f2b20..000000000 --- a/docs/en/solutions/Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md +++ /dev/null @@ -1,326 +0,0 @@ ---- -products: - - Alauda Container Platform - - Alauda DevOps -kind: - - Article -ProductsVersion: - - 4.x -id: KB261000025 ---- - -# Managing Platform Configuration and Onboarding Isolated Projects with Argo CD and Tekton on ACP - -Use a platform Git repository to review and preserve shared configuration. Use an onboarding pipeline to create a project's namespaces and tool-side resources, then propose its deployment configuration through a merge request. Argo CD reconciles the objects owned by Git; the onboarding tasks reconcile the resources they create in external tools. - -This article is the platform part of [Alauda DevOps Best Practices](./Alauda_DevOps_Best_Practices_Overview.md). It assumes one ACP project and separate tool-side tenants per project. Its configuration baseline is Pipelines 4.15, Artifact Hub Shim 1.0, Connectors 1.14, and GitOps 4.4 on a compatible ACP installation. Teams sharing one namespace and one tool tenant need a different boundary model. - -The [companion samples](https://github.com/AlaudaDevops/devops-best-practices-samples) contain the complete reference files. Names such as `shop`, `payments`, `platform-connectors`, and `registry.example.com` are fictional. Replace them, the image placeholders, group resource names, policy identities, and encrypted Secret placeholders for the target environment. - -## Establish the ownership model - -Keep three kinds of repository separate: - -| Repository | Contents | Owner | -| --- | --- | --- | -| Platform repository | Component configuration, admission policies, encrypted administrator credentials, project declarations, and platform Application definitions | Platform team | -| Template repository and catalog | Versioned shared Pipelines and Tasks; initial project GitOps repository content | Platform team | -| Project repositories | Application source and `.tekton/`; environment manifests and digest references in the project GitOps repository | Project team | - -Run Templates are execution settings in project namespaces. They are distinct from versioned catalog Pipeline definitions. Keep application manifests out of the platform repository, and keep platform policy ownership out of application repositories. - -```mermaid -flowchart TB - MR[Review platform change] --> Git[Platform repository] - Git --> Argo[Argo CD] - Argo --> Components[Component settings] - Argo --> Policies[Platform policies] - Argo --> Credentials[Encrypted administrator credentials] - Argo --> Declarations[Published project declarations] - Declarations --> Onboard[Tekton onboarding] - Onboard --> Tools[GitLab Harbor Nexus SonarQube] - Onboard --> Namespaces[Project namespaces and identities] - Onboard --> Seed[Seed project GitOps repository] - Onboard --> Registration[Propose platform registration MR] - Registration --> Git - Seed --> ProjectArgo[Project Applications] -``` - -Assign one owner to each resource or field. Argo CD self-healing applies to objects it tracks; it does not reconcile every object in the cluster or reverse external tool operations. Removing a declaration is not an automated decommissioning procedure. - -## Prepare the platform before bootstrap - -Install components using their product installation instructions: - -- [Pipelines](https://docs.alauda.io/alauda-devops-pipelines/4.15/install.html), including the required [PaC component](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/install/manage_pac.html) and [Manual Approval Gate](https://docs.alauda.io/alauda-devops-pipelines/4.15/how_to/manual_approval_gate_operator.html). -- [Connectors](https://docs.alauda.io/alauda-devops-connectors/1.14/install/install.html). -- [GitOps](https://docs.alauda.io/gitops/4.4/install_gitops/index.html). -- [Kyverno](https://docs.alauda.io/container_platform/4.4/security/security_and_compliance/compliance/install.html) and the sealed-secrets controller. Their CRDs must exist before syncing policies and SealedSecrets. - -An administrator creates the management namespace, `platform-connectors` in the samples, and installs the four Connectors automatic creation Tasks there. These Tasks are installed from the Connectors documentation; they are not fetched from the general Task catalog. Prepare administrator access to the four tools and encrypt the credentials for the target sealed-secrets controller before committing them. - -Create the Chains signing key and central registry credential outside Git. The central registry credential must exist before syncing the component layer that mounts it. Give it access only to registry projects that Chains must read and sign, and update that access when a project is onboarded. - -Register the platform repository with Argo CD and provide read access to each project GitOps repository. A repository credential template can cover the approved GitLab URL prefix; narrower templates must be added per project. Use repository URLs ending in `.git` for Application and AppProject GitLab references. Use the cluster name registered by Alauda GitOps for both Application destinations and AppProject destination constraints. - -Create the ACP project through the platform before onboarding it. The pipeline exports that project's manifest for subsequent registration. Importing an existing project into Git needs the same review as creating one: the project Application can later prune that resource. - -Platform administrators are responsible for webhook setup and event-delivery verification for platform, project GitOps, and application repositories. Registration with a token authorized to manage repository webhooks supports controller-managed webhook creation and deletion. For centralized management, follow [Create a Git Secret for PAC](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/create_git_secret.html). The sample's Developer-level GitOps token cannot manage webhooks; complete the administrator webhook configuration and test a real event before accepting onboarding. - -Keep Harbor projects private. Configure Nexus anonymous access and SonarQube permissions according to the project-isolation requirements in their Task guides. Do not infer isolation merely from the presence of separate credentials. - -For a disconnected environment, prepare local catalog content, pinned tool and base images, dependency repositories, certificates, and vulnerability databases before running pipelines. - -## Decide the 18 platform baselines - -The table identifies the platform decision and its repository layer. Values and detailed steps belong in the linked product documentation. These are administrator-managed recommendations, with maturity and prerequisites determined by the selected release. - -| # | Decision | Why it is shared | Layer and guidance | -| --- | --- | --- | --- | -| 1 | Separate Repository access tokens from webhook administration; use reviewed default-branch definitions and an explicit GitLab provider URL. | Credential scope and pre-merge execution trust should be consistent. | Credentials and project: [PaC Repository configuration](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/advanced_repository_config.html). | -| 2 | Standardize merge-request retries with `/test `. | Teams use one supported entry. | Project template: [Trigger PAC Pipelines](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/trigger_pipeline.html). | -| 3 | Separate platform-provided Repository parameters from application inputs. | Addresses and Connector names have a defined owner. | Project: [Advanced Repository Configuration](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/advanced_repository_config.html). | -| 4 | Decide Harbor event handoffs. | Event endpoints and validation need consistent ownership. | Component: [Harbor events](https://docs.alauda.io/alauda-devops-pipelines/4.15/triggers/how_to/harbor_events.html). | -| 5 | Schedule reconciliation and rotation with failure alerts. | The platform owns the interval and operational response. | Component: [ScheduledTrigger](https://docs.alauda.io/alauda-devops-pipelines/4.15/triggers/how_to/scheduledtriggers.html). | -| 6 | Standardize EventListener exposure. | TLS, routes, and webhook validation belong to the platform. | Component: [Automatic exposure rules](https://docs.alauda.io/alauda-devops-pipelines/4.15/triggers/how_to/trigger-wrapper-config.html). | -| 7 | Orchestrate tool-side tenant creation with the four product Tasks. | Administrators retain tool-wide credentials. | Credentials and project: tool Task guides below. | -| 8 | Define long-lived credential rotation for each tool. | Expiry and renewal behavior differ by tool. | Component and credentials: [Credential rotation](https://docs.alauda.io/alauda-devops-connectors/1.14/how_to/automatically_create_connectors_for_a_project.html#credential-rotation). | -| 9 | Configure Chains signing keys and image verification. | The platform owns the signer and distributes its public key. | Component, credentials, policy: [Signing keys](https://docs.alauda.io/alauda-devops-pipelines/4.15/chains/configure/signing_key_configuration.html). | -| 10 | Use Connector proxy access while tracking long-lived credential exceptions. | Access boundaries and rotation need a central owner. | Credentials: [Connectors Proxy](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors/concepts/connectors_proxy.html) and [CSI Driver](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors/concepts/connectors_csi.html). | -| 11 | Apply namespace Pod Security and separate build namespaces. | Build tooling and workloads have different privilege needs. | Policy and project: [Restricted standard](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/comply_with_pod_security_restricted.html). | -| 12 | Install approval and define protected-environment groups and promotion rules. | Approval ownership is a platform control. | Component, project, policy: [Manual Approval Gate](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/manual_approval_gate.html). | -| 13 | Establish platform and project policy layers. | Projects can add restrictions without weakening the platform baseline. | Policy: [Constrain pipeline execution](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/constrain_pipeline_execution_with_kyverno.html). | -| 14 | Own the shared, locally available catalog. | Reuse and offline content need governance. | Component: [Author Catalog Resources](https://docs.alauda.io/alauda-devops-artifacthub-shim/1.0/catalog/how_to/author_catalog_resources.html). | -| 15 | Publish versioned central Pipelines. | Projects adopt reviewed versions explicitly. | Component: [Centralized Pipeline management](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/hub_pipeline_run_template_centralized_management.html). | -| 16 | Select Pruner defaults and namespace override policy. | Cleanup affects shared cluster history and capacity. | Component: [Pruner configuration](https://docs.alauda.io/alauda-devops-pipelines/4.15/pruner/configure/pruner_configuration.html). | -| 17 | Define Results storage, watch scope, authentication, and retention. | Audit records need storage independent of live objects. | Component: [Results retention](https://docs.alauda.io/alauda-devops-pipelines/4.15/results/configure/retention_policy_configuration.html). | -| 18 | Enable metrics and operational monitoring. | Operators need evidence of controller and execution health. | Component: [Metrics Collection](https://docs.alauda.io/alauda-devops-pipelines/4.15/configure/metrics_collection.html). | - -### Separate policy scope from definition trust - -Use platform ClusterPolicies for shared controls and namespaced Policies for project-specific restrictions. Restrict direct TaskRun and CustomRun creation by the actual submitting identity; client-supplied owner references alone are not an authorization boundary. Enumerate controller identities and review their permissions. - -Optionally restrict PipelineRun references to approved resolver types. This abbreviated policy illustrates only the source-type decision; adapt namespace exclusions for every platform system namespace: - -```yaml -apiVersion: kyverno.io/v1 -kind: ClusterPolicy -metadata: - name: pipelinerun-source-baseline -spec: - background: false - rules: - - name: approved-resolver-only - match: - any: - - resources: - kinds: [tekton.dev/v1/PipelineRun] - operations: [CREATE] - exclude: - any: - - resources: - namespaces: [platform-connectors] - validate: - failureAction: Audit - message: "pipelineRef must use an approved resolver" - deny: - conditions: - all: - - key: "{{ request.object.spec.pipelineRef.resolver || '' }}" - operator: AnyNotIn - value: [cluster, hub, git] -``` - -This does not constrain a resolver's URL, catalog, namespace, version, definition content, or runtime credential scope. It also rejects inline `pipelineSpec` when enforced. Convert the sample's inline validation flow to a catalog Pipeline before enabling that restriction for project repositories. Restrict PolicyException creation or disable exceptions according to platform policy. - -The sample's `argocd-project-namespace-boundary` policy constrains writes of Role, RoleBinding, ResourceQuota, LimitRange, and NetworkPolicy by the configured Argo CD identities in labelled project namespaces. It allows the platform-owned registration path and requires `allowExistingViolations: false`. Adapt both Argo CD identities for the target cluster and verify the intended allow and deny cases before relying on the boundary. Install and verify the policy on every destination cluster to which the boundary should apply. - -Kyverno availability and recovery are platform operating concerns. Prepare a local runbook; this series does not prescribe the cluster's write behavior during a policy-service outage. See [Pipeline Policy Constraints with Tekton and Kyverno](./Pipeline_Policy_Constraints_with_Tekton_and_Kyverno.md) for the policy design. - -## Organize and synchronize the platform repository - -The sample is split into four ownership layers and the onboarding installation: - -```text -platform-config/ -├── argocd/apps/ # Root and child Application definitions -├── components/ # TektonConfig and component options -├── policies/ # Platform admission policies -├── credentials/ # Administrator Connectors and sealed placeholders -├── projects/ # Declarations and reviewed registration output -├── templates/ # Registration rendering templates -├── onboarding/ # Pipelines, Run Templates, schedules, and RBAC -└── .tekton/ # Validation and changed-project dispatch -``` - -Copy `onboarding/` from the sample to the platform repository root as described by its README. Register the repository read-only with Argo CD and use one child Application per layer. The root Application manages those Application definitions. - -For partial singleton component configuration, use server-side apply so the platform repository owns only the specified fields. The samples also set `argocd.argoproj.io/compare-options: ServerSideDiff=true`. Review the generated diff and the operator's field ownership before synchronization. The component layer uses `prune: false` so that removing a fragment does not delete the singleton TektonConfig. Establish the component layer's automated synchronization behavior in the target environment before enabling ongoing self-healing. - -The credential layer does not enable self-healing: seal credentials for the target controller and plan how rotations update live Secrets and encrypted source. Other layers can use prune and self-heal according to their ownership. Namespaces are created by onboarding; do not add a second namespace creator with `CreateNamespace`. - -ACP maintains the AppProject associated with an ACP project. The registration patch manages only the intended repository and destination fields. Reconcile the effective destinations with the platform-managed entries, and use the admission boundary for object-kind restrictions. Do not rely on an Application's sync status alone to prove the deployment boundary. - -Review deletion carefully. Pruning a registered ACP project can delete its same-named namespace and its Secrets, Connectors, and Repository objects. It does not reverse tool-side creation or remove every build, delivery, or environment namespace. Decommissioning requires a separate approved procedure. - -### Validate changes before merging - -Both the platform and project GitOps templates include `.tekton/validate.yaml`, which composes catalog `git-clone` and `run-script` Tasks. Replace its tool image with a locally available image containing the required shell and Kustomize commands. Establish its webhook before the first merge-request run. With default-branch definition provenance, a change to the validation definition is first exercised after it has entered that branch. - -Validate every directory owned by an Application, and add new directories to the validation paths. Re-run a merge-request check with `/test validate`. YAML parsing and Kustomize rendering do not validate CRD admission behavior; use the target schemas and an isolated project for that acceptance step. - -## Declare a project and run onboarding - -The declaration is a sample schema, not an ACP API. The pipeline validates its supported naming conventions. A complete `shop` declaration includes the following fields; use the sample's full file: - -```yaml -name: shop -platformProject: shop -owners: - - shop-platform-owners -environments: [test, prod] -tools: [gitlab, harbor, nexus, sonarqube] -approvers: - prod: group:release-managers -imagePullFrom: [] -namespaces: - workloads: [shop, shop-test, shop-prod] - build: shop-build - delivery: shop-cd -gitlab: - group: shop - subgroups: [apps, gitops] -harbor: - projects: [shop, shop-prod] -nexus: - repositories: - - name: shop-maven - format: maven2 - type: hosted - - name: shop-npm - format: npm - type: hosted -sonarqube: - project: shop -``` - -`owners` contains ACP group resource names without a `group:` prefix; approval entries use `group:`. A console display name is not the resource name. Group membership changes belong to group administration, rather than edits naming individuals in every declaration. - -Submit the declaration, project-specific onboarding permissions, and schedule through a platform merge request. Confirm that the declaration and onboarding Applications have synchronized; synchronize them manually when using a manual sync policy. Then examine the dispatcher result and every child onboarding run. A successful merge or dispatcher does not by itself establish complete project readiness. - -The sample dispatches changed declarations after a merge. A path filter can also admit a run with no relevant declaration changes; the dispatcher is responsible for selecting actual declarations. A deleted declaration is skipped, rather than interpreted as an instruction to delete a project. - -### Understand the seven onboarding stages - -| Stage | Work | Owner or mechanism | -| --- | --- | --- | -| 1 | Export the existing ACP project without runtime metadata; create or reconcile labelled namespaces and delivery identities. Workloads use restricted Pod Security; the build namespace is separate. | Sample orchestration and Kubernetes APIs | -| 2 | Create the GitLab tenant group and a project access token; make a separate writer Connector for GitOps delivery. | GitLab automatic creation Task | -| 3 | Create private source and production Harbor projects, distribute image pull configuration, and create separate source-read and production-write Connectors for release. | Harbor automatic creation Task | -| 4 | Create Nexus repositories and a scoped user, then write the project Connector. | Nexus automatic creation Task | -| 5 | Create the SonarQube user, token, and project permission template, then write the Connector. | SonarQube automatic creation Task | -| 6 | Seed the empty project GitOps repository and create its PaC Repository and access Secret. Complete and verify webhook configuration separately. | Sample template seeding and PaC resources | -| 7 | Render project Applications, AppProject patch, owner and Connector bindings, and the exported ACP project. Open a platform registration merge request. | A separate `gitops-repo-update` PipelineRun | - -The registration step proposes Git changes instead of directly applying Argo CD resources. Review the entire diff, including RBAC and destination changes. Keep sufficient execution capacity for both the parent and child run: the waiting parent still reserves its Pod resources. Cancellation and cleanup must account for the independently created child run. - -The pipeline runs in the management namespace with administrator Connectors. Permission to create Pods or PipelineRuns there is effectively access to those credentials, even without API permission to read Secrets. Limit that namespace and the onboarding identity to platform automation and administrators. - -### Reuse the product Tasks - -The four Tasks have different parameters and rotation behavior. Read their installation, access, and prerequisite instructions: - -- [GitLab tenant group and Connector](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors-gitlab/how_to/using_gitlab_connector_automatic_creation_task.html). -- [Harbor resources and Connector](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors-harbor/how_to/using_harbor_connector_automatic_creation_task.html). -- [Nexus resources and Connector](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors-nexus/how_to/using_nexus_connector_automatic_creation_task.html). -- [SonarQube tenant and Connector](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors-sonarqube/how_to/using_sonarqube_connector_automatic_creation_task.html). - -Set the target `connector` as `namespace/name`. Set GitLab access levels explicitly: the project access token and the GitOps writer have different responsibilities. In the sample, project access uses `api` and `read_repository`; the writer additionally uses `write_repository`. Connectors CSI mounts use the `connectors` attribute, with the namespace included. - -The sample writes only to the current cluster using an explicitly authorized ServiceAccount. For cross-cluster application, follow each Task's Kubernetes Connector and `kubeconfig` Workspace instructions. Do not assume that the management namespace's default ServiceAccount has the required write permissions. - -An alternative product workflow creates project Connectors from namespace events: [Automatically Create Connectors for a Project](https://docs.alauda.io/alauda-devops-connectors/1.14/how_to/automatically_create_connectors_for_a_project.html). If choosing that path, assign one creator and rotation owner per tenant and resource. Avoid two independent reconcilers managing the same credentials. - -## Register repositories and verify events - -Set the self-managed provider URL and reviewed definition source on every PaC Repository. The following fragment omits credential data; create its referenced Secret through the approved credential path: - -```yaml -apiVersion: pipelinesascode.tekton.dev/v1alpha1 -kind: Repository -metadata: - name: shop-gitops - namespace: shop -spec: - url: https://git.example.com/shop/gitops/config - git_provider: - type: gitlab - url: https://git.example.com - secret: - name: shop-gitops-auth - webhook_secret: - name: shop-gitops-auth - settings: - pipelinerun_provenance: default_branch -``` - -Set the provider URL explicitly so completion requests and the Repository token use the intended GitLab instance. The PaC repository URL differs from the `.git` URL used by Argo CD. `gitops/config` is a repository beneath the `gitops` subgroup, rather than a repository path conflicting with that subgroup's name. - -The sample's project GitOps token is Developer-level and requires administrator-managed webhook setup. Verify a fresh event and its resulting run. Keep webhook management credentials available through repository decommissioning, and check for remaining code-platform webhooks afterward. The application's Repository belongs in the build namespace, where CI executes. - -## Reconcile and rotate deliberately - -Use repeated runs of the same supported parameters for reconciliation. Do not equate Connector `Ready=True` with an unexpired, usable tool token; perform an authorized tool request or workload operation before and after rotation. - -| Change | Required operating action | -| --- | --- | -| A supported declaration field changes | Review Task-specific recreation and rotation effects, then reconcile the project. | -| A new environment is added | Add its GitOps directory and validation path through a project merge request as well as changing the declaration. | -| A template changes | Propose updates to existing project repositories separately. Seeding copies only into an empty repository. | -| A credential is due for rotation | Run the relevant Task on a schedule shorter than expiry minus a safety margin; alert and retry on failure. | -| A credential has no expiry | Rotate at the interval required by policy; choose the Task's refresh behavior explicitly. | - -The sample's supported GitLab subgroups are `apps` and `gitops`. Changing that convention requires a reviewed pipeline change, rather than only a declaration edit. Tool-side identity changes can recreate accounts or credentials; inspect the product Task's contract before changing names or project sets. - -Do not overlap runs for the same tenant. Arrange rotation outside active pipeline windows and monitor failed runs before the current credential expires. CSI workload-token issuance is separate from rotating the tool's long-lived credential. Consult the Task guide for expiry recovery; define a local recovery procedure rather than depending on an unobserved natural-expiry path. - -If enabling Connector approval, prepare grants for every affected workload, enable `enable-connectors-approval`, immediately create the required AccessPolicies, and then enable `enable-connector-proxy-permissions`. The sample's optional administrator AccessPolicy is excluded from the default Kustomization and is applied only after the feature is enabled. Use RBAC for the documented cross-namespace grants and keep approval-gated production Connectors free of direct proxy grants. See the [delivery article](./From_Commit_to_Production_on_ACP.md#gate-the-production-connector-after-approval) for the complete rollout boundary. - -## Accept the project boundaries - -| Boundary | What must be demonstrated | -| --- | --- | -| Namespaces and Pod Security | Workload namespaces have the intended labels; builds and delivery use their separate namespaces and identities. | -| Deployment scope | Effective AppProject destinations and platform admission permit only the intended project deployment path. Test forbidden RBAC and quota writes with the actual Argo CD identities. | -| Tool access | GitLab, Harbor, Nexus, and SonarQube authorization matches the tenant. Use positive controls before negative cross-project tests. | -| Credential access | Project users cannot create Pods or runs in administrator or signing namespaces. Inventory image pull Secrets, PaC clone credentials, and central Chains credentials separately. | -| Event routing | A fresh repository event or merge-request retry produces the expected run in the intended namespace. | -| Rotation | A successful non-overlapping run updates the intended credential and an authorized operation works afterward. | - -Run `acceptance/02-platform-and-onboarding.sh` from the sample in an isolated acceptance project. Its companion delivery script verifies the image path after the first application build. Check every child onboarding run, the four Connectors, the seeded repository, registration merge request, and Applications. The initial placeholder digest is not deployable; workload health follows the first real deployment. - -For cross-project image denial, first verify that the exact image exists and can be pulled in its own project. Then test an unauthorized project, distinguish `unauthorized` from `not found` and Pod Security rejection, and repeat in the opposite direction using an image that exists there. Delete temporary probe resources after the checks. - -Test self-healing only on a disposable resource in the acceptance project. Record its UID and recovery manifest, perform the approved change, and confirm recreation with a different UID. Restore it if the check fails. This is separate from proving ongoing automatic reconciliation of the operator-managed component layer. - -## Preserve audit records and plan recovery - -Choose one cleanup mechanism and review its scope before enabling it. Use event-based Pruner according to the global and namespace configuration guides; disable the older periodic mechanism when migrating. Verify each selected retention mode in the target environment before it can remove shared run history. - -Use external PostgreSQL and the documented log storage for Results. Define watch scope, authentication, and one retention policy for the reference configuration. Verify read authorization through the Results API, rather than inferring it from Kubernetes resource visibility. Preserve approval responses separately before cleanup removes the ApprovalTask objects. - -Scope Results Watcher before enabling it: default watching can affect finished runs across namespaces and add `results.tekton.dev/*` finalizers. Disabling archiving does not remove finalizers already present. Follow the product recovery procedure before deletion and treat external Results storage as the audit source after cluster objects are pruned. See [S3 storage](https://docs.alauda.io/alauda-devops-pipelines/4.15/results/configure/s3_storage_configuration.html) and [Results retention](https://docs.alauda.io/alauda-devops-pipelines/4.15/results/configure/retention_policy_configuration.html). - -Git does not replace backups of credentials and external data. Before a platform rebuild, the platform team must prepare and rehearse recovery of these dependencies: - -1. Compatible platform components, Kyverno, and sealed-secrets CRDs and controllers. -2. The sealed-secrets decryption key, or re-sealed credentials for the new controller. -3. Chains signing keys and the central registry credential; coordinate any verification-key change with image admission. -4. The management namespace and installed automatic creation Tasks. -5. Argo CD repository access and project repository credential templates, plus PaC access and webhook configuration. - -After preparing those dependencies, synchronize the platform layers, run onboarding for the declared projects, review registration changes, and complete the acceptance checks. This is a dependency outline; a complete empty-cluster or second-cluster recovery runbook must be exercised in the target environment. - -Before production, complete the sample's hardening work: isolate pre-merge validation from administrator credentials, narrow the AppProject used for project registration, protect the GitOps writer's namespace, install promotion Core rules, and restrict production image sources. Restrict direct cluster writes alongside Git review. Template upgrades, decommissioning, capacity sizing, offline package distribution, and customer change-management integration require separate operating procedures. - -Continue with [From Commit to Production](./From_Commit_to_Production_on_ACP.md) to use the onboarded project's build, test, promotion, and production GitOps paths. diff --git a/docs/zh/solutions/Alauda_DevOps_Best_Practices_Overview.md b/docs/zh/solutions/Alauda_DevOps_Best_Practices_Overview.md deleted file mode 100644 index 82d25d2d4..000000000 --- a/docs/zh/solutions/Alauda_DevOps_Best_Practices_Overview.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -products: - - Alauda Container Platform - - Alauda DevOps -kind: - - Article -ProductsVersion: - - 4.x -id: KB261000020 -sourceSHA: 8cdf0c0809912524e67d79728e85bedcb3ec2f8988c5d466f6ef107d2a376ab5 ---- - -# Alauda DevOps 最佳实践：概述和场景指南 - -本系列帮助应用程序和平台团队将 Alauda DevOps 功能结合到交付工作流中。从一个可工作的管道开始，将构建输出连接到受控发布，然后为多个隔离项目标准化平台。 - -配置基线为 Alauda DevOps Pipelines 4.15、Artifact Hub Shim 1.0、Connectors 1.14 和 Alauda Container Platform GitOps 4.4，适用于兼容的 ACP 安装。在选择软件包时，请使用每个组件的兼容性要求。示例使用 GitLab、Harbor、Nexus 和 SonarQube。它们描述了一个参考实现，生产使用前需要环境准备和验收检查。 - -该系列有三个入口点： - -| 您的起点 | 接下来阅读 | -| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 您需要一个用于一个代码库的构建或测试管道。 | [开始一个管道](#start-a-pipeline) 在下方。 | -| 一个管道已经在运行；您需要从提交到生产的可追溯路径。 | [从提交到生产在 ACP](./From_Commit_to_Production_on_ACP.md)。 | -| 您操作一个共享平台，需要可重复的配置和项目入驻。 | [管理平台配置和入驻隔离项目](./Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md)。 | - -[伴随示例](https://github.com/AlaudaDevops/devops-best-practices-samples) 包含平台代码库、项目声明、入驻管道、GitOps 代码库模板、应用程序交付示例和验收脚本。在使用之前，请替换示例地址、镜像引用、身份和加密凭证占位符。 - -## 整体设计 - -交付层将一个更改从源移动到不可变镜像，然后到环境。平台层提供可重用的定义、工具访问、命名空间和操作设置。控制层决定什么可以运行，谁批准发布，以及必须保留什么证据。 - -```mermaid -flowchart TB - subgraph Controls[控制层] - Policy[管道和镜像准入] - Approval[发布批准] - Audit[运行和日志保留] - end - subgraph Delivery[交付层] - Source[源代码库] --> Trigger[PaC 或触发器] - Trigger --> Build[构建和扫描] - Build --> Image[由摘要标识的镜像] - Image --> Test[测试部署] - Test --> Promote[提升所选摘要] - Promote --> Production[生产 GitOps 更改] - end - subgraph Platform[平台层] - Catalog[版本化目录管道和任务] - Connectors[项目和管理员连接器] - Git[平台配置和项目声明] - end - Policy -.-> Trigger - Policy -.-> Production - Approval -.-> Promote - Audit -.-> Build - Catalog -.-> Build - Connectors -.-> Build - Git -.-> Connectors -``` - -应用程序开发人员负责源代码和应用程序交付配置。平台管理员负责共享组件、准入规则、管理员凭证和入驻。发布批准者在检查其构建和测试证据后授权所选摘要。将发布身份与构建身份分开。 - -## 开始一个管道 - -选择满足团队需求的最简单定义模型。这些模型可以共存。 - -| 模型 | 定义和触发 | 使用场景 | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -| 集群中的管道 | 在项目命名空间中创建一个管道。将参数、工作区和集成保存在运行模板中。手动启动、通过触发器或按计划启动。 | 少量管道需要简单的执行入口。 | -| 作为代码的管道 (PaC) | 将 PipelineRun 定义保存在应用程序的 `.tekton/` 目录中。代码事件启动运行并将结果报告到合并请求中。 | 定义应随源代码演变并参与合并请求检查。 | -| 中央管理模板 | 在目录中维护一个版本化的管道，或在受控命名空间中维护一个管道。项目通过运行模板或使用解析器的 PaC PipelineRun 提供参数。 | 多个项目应共享相同的标准工作流。 | - -对于 PaC 重试，在合并请求中使用 `/test `，并参考 [触发 PaC 管道](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/trigger_pipeline.html) 获取完整语法。每个事件使用一个事件路由：PaC 或触发器。为同一事件启用两个路由可能会启动重复工作。 - -从 [运行模板](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/run_template.html)、[配置 GitLab 仓库](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/guides/configure_gitlab_repo.html) 或 [通过 Hub 管道和运行模板进行集中管理](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/hub_pipeline_run_template_centralized_management.html) 开始。[应用程序 CI/CD 教程](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/tutorials/index.html) 提供了指导实施。 - -## 连接交付阶段 - -| 需求 | 推荐组合 | 详细指导 | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| 构建可追溯的工件 | 重用目录任务，扫描输出，并将其摘要传递给后续阶段。 | [从提交到生产](./From_Commit_to_Production_on_ACP.md)。 | -| 部署到开发或测试环境 | 当环境状态的 Git 历史不必要时，直接按摘要更新工作负载。 | [应用程序 CI/CD 教程](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/tutorials/index.html)。 | -| 部署到生产 | 审查对生产 GitOps 仓库的更改；Argo CD 会协调所选摘要。 | [Alauda Container Platform GitOps](https://docs.alauda.io/gitops/4.4/)。 | -| 分离生产工件访问 | 批准并将所选镜像按摘要复制到生产注册项目中。 | [使用 Skopeo 复制提升工件](https://docs.alauda.io/alauda-devops-artifacthub-shim/1.0/catalog/how_to/promote_artifacts_with_skopeo_copy.html)。 | -| 记录谁批准了发布 | 添加 ApprovalTask，使用组资源名称，并保留其批准响应。 | [手动批准门](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/manual_approval_gate.html)。 | -| 验证镜像签名 | 中央配置 Chains 密钥和注册访问；在提升和部署准入前按摘要验证镜像。 | [签名密钥配置](https://docs.alauda.io/alauda-devops-pipelines/4.15/chains/configure/signing_key_configuration.html)。 | -| 移交工件事件 | 将 Harbor 事件映射到下一个管道，携带摘要。分别检查扫描和签名证据。 | [使用 Harbor 事件触发器](https://docs.alauda.io/alauda-devops-pipelines/4.15/triggers/how_to/harbor_events.html)。 | - -提升操作复制所选镜像；它并不表明该镜像通过了 CI。批准者必须将摘要与成功的受信构建和测试环境进行匹配。签名建立了配置签名者的声明；其意义还取决于对签名密钥的控制和允许运行的定义。 - -示例故意将测试 CD、提升和生产 CD 保持为手动启动的运行。它们的输入来自前一个运行的摘要结果。由 Harbor 驱动的自动化是一个单独的集成步骤。发布教程的第一次部署由管理员执行；后续发布遵循配置的交付路径。 - -## 准备共享平台 - -平台设置是管理员的决策。分阶段推出，并检查所选发布的 [功能成熟度](https://docs.alauda.io/alauda-devops-pipelines/4.15/overview/feature_maturity.html)。 - -| 平台关注点 | 推荐方法 | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 工具访问 | 使用项目范围的连接器。代理访问使用短期工作负载令牌。将镜像拉取凭证、PaC 克隆凭证和 Chains 注册凭证作为单独的长期凭证责任进行管理。 | -| 项目入驻 | 协调四个连接器自动创建任务，然后为项目 GitOps 仓库提供种子，并通过合并请求提出平台注册。完成管理员的前提条件和验收检查。 | -| 平台配置 | 将组件设置、策略、加密管理员凭证和项目声明保存在平台代码库中。为每个资源或字段分配一个所有者。 | -| 命名空间隔离 | 使用单独的项目命名空间和工具侧租户。分离构建、交付和工作负载命名空间，并限制对管理员命名空间的访问。 | -| 执行策略 | 使用平台 ClusterPolicies 和项目 Policies。限制直接创建 TaskRun 和 CustomRun。可选地要求批准的解析器类型和坐标。在检查预期工作流后，从审计转移到强制执行。 | -| 清理 | 选择一种清理机制。对于基于事件的 Pruner，在启用删除之前检查全局默认值和命名空间覆盖设置。 | -| 审计历史 | 将运行记录和日志存储在外部结果存储中，并设定明确的保留期。在删除对象之前单独导出批准证据。 | -| 定期工作 | 使用 ScheduledTrigger 或 CronJob 进行协调和轮换，设置故障警报，并确保租户没有重叠运行。 | - -结果观察者范围值得单独推出决策。其默认观察范围可能会影响集群中的已完成运行，并添加 `results.tekton.dev/*` 最终处理程序。在启用之前对其进行范围限制。禁用归档不会删除现有的最终处理程序；在清理之前遵循产品恢复程序。在 Pruner 删除集群对象后，外部结果存储是审计来源。 - -[平台文章](./Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md) 解释了 18 个平台决策、代码库布局、所有权边界、入驻工作流、轮换和验收检查。 - -## 在没有互联网访问的情况下操作 - -通过平台的批准内部服务提供目录、固定工具和基础镜像、软件包依赖项、证书和漏洞数据库。运行时管道必须从本地目录或集群源解析任务和管道。示例 CI 配置将 Trivy 指向 `registry.example.com/mirror/trivy-db:2`；将其替换为可访问的数据库镜像并授予扫描器访问权限。 - -网络隔离的程度、团队数量和所需的批准证据是平台团队必须决定的部署输入。容量规划、迁移和退役自动化、平台灾难恢复、客户变更管理集成和离线软件包分发程序超出了本系列的范围。为目标环境定义这些程序。 - -## 相关信息 - -- [Pipelines 4.15](https://docs.alauda.io/alauda-devops-pipelines/4.15/) -- [Artifact Hub Shim 1.0](https://docs.alauda.io/alauda-devops-artifacthub-shim/1.0/) -- [Connectors 1.14](https://docs.alauda.io/alauda-devops-connectors/1.14/) -- [GitOps 4.4](https://docs.alauda.io/gitops/4.4/) -- [使用 Tekton 和 Kyverno 的软件供应链安全](./Software_Supply_Chain_Security_of_Alauda_Container_Platform_with_Tekton_and_Kyverno.md) -- [使用 Tekton 和 Kyverno 的管道策略约束](./Pipeline_Policy_Constraints_with_Tekton_and_Kyverno.md) diff --git a/docs/zh/solutions/From_Commit_to_Production_on_ACP.md b/docs/zh/solutions/From_Commit_to_Production_on_ACP.md deleted file mode 100644 index 6b417b1b5..000000000 --- a/docs/zh/solutions/From_Commit_to_Production_on_ACP.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -products: - - Alauda Container Platform - - Alauda DevOps -kind: - - Article -ProductsVersion: - - 4.x -id: KB261000023 -sourceSHA: 65726b2d0abae3f8253b53738b5e2e4262c43949d7fca67695e1c35b709ef205 ---- - -# 从提交到生产在 ACP 上：选择触发器、部署和发布控制 - -使用本文来选择管道定义的位置、部署如何使用构建输出，以及审批、推广和签名检查的归属。有关指导实施，请参阅 [原生应用 CI/CD 教程](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/tutorials/index.html)。 - -这是 [Alauda DevOps 最佳实践](./Alauda_DevOps_Best_Practices_Overview.md) 的交付部分。其配置基线为 Pipelines 4.15、Artifact Hub Shim 1.0、Connectors 1.14 和 GitOps 4.4。项目命名空间、工具侧资源和 Connectors 必须已经存在；[平台文章](./Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md) 解释了它们的准备工作。 - -[伴随示例](https://github.com/AlaudaDevops/devops-best-practices-samples) 使用一个虚构的 `shop` 项目。CI 在 `shop-build` 中运行；CD 和推广在 `shop-cd` 中运行；工作负载在 `shop-test` 和 `shop-prod` 中运行。请根据您的环境替换每个示例地址、工具镜像、组、凭证占位符和策略身份。确保漏洞数据库、工具镜像、基础镜像和依赖项在本地可用，以便进行离线执行。 - -## 在工作流中跟踪一个镜像身份 - -```mermaid -flowchart LR - Commit[合并应用更改] --> CI[构建和扫描] - CI --> Source[按摘要从源注册表获取镜像] - Source --> Test[在测试中部署和验证] - Test --> Approve[批准选定的摘要] - Approve --> Copy[将镜像复制到生产注册表] - Copy --> Sign[验证签名和来源] - Sign --> MR[审查生产 GitOps 更改] - MR --> Sync[Argo CD 同步和发布] -``` - -在部署、推广源、签名验证和审计关联中使用 `repository@sha256:`。标签帮助人们识别发布；单独的标签并不能识别不可变内容。Harbor 推送事件表明镜像已被推送，但并不表明成功扫描、测试、签名或批准。 - -当在已部署的镜像中发现漏洞时，修复它并使用相同的构建、推广和部署工作流发布新的摘要。保留构建证据和用发布记录替换漏洞镜像的决定。 - -## 选择定义的位置和运行的启动方式 - -| 模型 | 定义位置 | 触发器 | 适用场景 | -| ----------------- | ---------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------- | -| 集群管道 | 项目命名空间中的管道；执行设置在运行模板中 | 手动、触发器或计划触发器 | 少量集中操作的管道 | -| 代码中的管道 | 应用的 `.tekton/` 目录中的 PipelineRun 文件 | 推送和合并请求事件 | 与源和合并请求检查版本控制的定义 | -| 中央模板 | 版本化的目录管道，或受控集群命名空间中的管道 | 运行模板或带有 `pipelineRef` 的 PaC PipelineRun | 跨项目共享标准 | - -当集群管道足够时，从集群管道开始。当变更历史和合并请求体验重要时，添加 PaC。当项目应重用标准工作流时，使用中央模板。同一项目可以针对不同的作业使用这三者。针对特定事件选择一种路径，PaC 或触发器。 - -对于来自合并请求的重试，使用 `/test `。通过链接到 [触发 PAC 管道](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/trigger_pipeline.html) 保持完整语法在一个地方。 - -### 将 PaC 与中央模板结合 - -将事件注释和项目输入保留在 `.tekton/` 中。通过解析器和固定版本引用平台的管道。以下片段显示了应用示例使用的引用；这不是完整的 PipelineRun。使用示例的完整参数和工作区绑定。 - -```yaml -spec: - pipelineRef: - resolver: hub - params: - - name: catalog - value: catalog-pipelines - - name: kind - value: pipeline - - name: name - value: python-image-build-scan-deploy - - name: version - value: "0.3" -``` - -对于受控集群管道，使用 `resolver: cluster`。在 PaC 定义中避免裸露的 `pipelineRef.name`，当入场检查必须检查定义的来源时。请参阅 [解析器](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/concepts/resolver_concept.html) 和 [在 Git 中定义 PipelineRuns](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/maintain_pipeline_code.html)。 - -通过审查其固定版本的更改来升级目录管道。项目不会自动采用新发布的版本。为了可重复回滚定义，保留已审查的版本并定义发布坐标是否不可变。运行模板的版本更改是对现有模板的更改，而不是创建另一个模板的理由。 - -### 保护定义及其运行时凭证 - -对于自管理的 GitLab 实例，在每个 PaC `Repository` 上设置 `spec.git_provider.url`。没有该 URL，本文中描述的 PaC 行为 [高级存储库配置](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/advanced_repository_config.html) 可能会将完成状态请求和存储库令牌发送到 `gitlab.com`。为应用、平台和项目 GitOps 存储库显式设置提供者 URL。 - -在预合并运行必须使用已审查定义的地方，设置 `spec.settings.pipelinerun_provenance: default_branch`。这选择定义，而不是受信任的应用代码：合并请求运行仍然使用该定义挂载的凭证构建提议的源。限制这些凭证，并将合并请求镜像输出与发布候选分开。 - -示例将两个输出分开： - -| 定义 | 事件 | 镜像存储库 | 交付用途 | -| ------------------------------------------ | -------------- | ------------------------------------ | ------------------------------ | -| `sample-app/.tekton/ci.yaml` | 推送到 `main` | `registry.example.com/shop/hello` | 测试 CD 和推广的源 | -| `sample-app/.tekton/ci-merge-request.yaml` | 合并请求 | `registry.example.com/shop/hello-mr` | 临时合并请求工件 | - -示例的 Harbor Connector 具有项目级访问权限。分离存储库名称本身并不能强制凭证边界。为了更强的分离，使用一个独特的临时注册项目和一个不能写入发布候选镜像的凭证。在交付之前，检查所选摘要是否为成功受信任的 `main` CI 运行的 `IMAGE_DIGEST`。 - -两个示例 CI 定义通过 `ca-bundle` 工作区绑定 Connector 代理 CA。即使上游注册表使用公共受信任证书，代理的 CA 也是必需的。对于离线扫描，将 `trivyExtraArgs` 设置为使用平台的镜像漏洞数据库，例如 `--db-repository registry.example.com/mirror/trivy-db:2`。扫描器必须能够拉取该镜像。 - -平台和 GitOps 存储库验证示例组合了 `git-clone` 和 `run-script` 内联。如果平台启用禁止内联 `pipelineSpec` 的策略，则将该验证流程发布为目录管道，并通过解析器引用它。 - -## 根据环境选择部署路径 - -| 路径 | 选定摘要如何到达环境 | 权衡 | -| ----------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------- | -| 直接部署 | 任务如 `workload-apply`、`helm-upgrade` 或 `run-script` 更新工作负载。 | 移动部件更少；Git 不持有环境状态的第二份副本。 | -| GitOps | 更改更新 Git 中环境的镜像引用；Argo CD 进行协调。 | 可审查的环境状态和历史；需要一个存储库和同步路径。 | - -一个有用的起点是将直接部署用于开发或测试，将 GitOps 用于生产。示例在测试和生产中都使用 GitOps，以便在两个环境中使用相同的协调路径。 - -对于直接部署，在 `workloadContainers` 中使用摘要；使用小写的 `workloadKind`，例如 `deployment`。运行身份需要访问读取和更新目标工作负载。请查阅目录任务以获取其发布、超时、回滚和跨集群选项。 - -对于 GitOps，每个环境使用一个目录和一个原生应用。将每个镜像摘要保留在一个地方，例如 Kustomize 的 `images` 条目： - -```text -gitops/ -├── base/ -└── envs/ - ├── test/kustomization.yaml - └── prod/kustomization.yaml -``` - -在示例中，测试 CD 使用 `submitMode: direct`；生产 CD 使用 `submitMode: pr`。生产覆盖层以生产注册表存储库为基础，因此发布仅更改其摘要。第一次生产部署等待推广的镜像。 - -在代码平台中强制执行生产 Git 审查。使用受保护的分支，并在支持的情况下进行代码所有者审批。其他选项包括单独受保护的生产分支或存储库，或经过审查的服务器端策略。仅分支保护并不会创建目录级保护。移除直接生产写入访问权限，以避免绕过所选的审查路径。 - -### 在构建、推广和 GitOps 之间传递结果 - -`gitops-repo-update` 是一个管道，并作为单独的 PipelineRun 运行。将选定的摘要作为参数传递给其更新脚本。每次运行使用一个新的源工作区卷和一个包含脚本使用的每个命令的镜像。`submitMode: pr` 还需要配置的 GitLab CLI 镜像和具有 API 访问权限的令牌。 - -示例使用 `sed` 更新 `digest:` 行，并使用 Kustomize 验证呈现的镜像。这保留了一行生产差异。避免使用更改无关格式或镜像字段的重写操作。GitOps 写入令牌需要克隆、推送和创建合并请求所需的范围；将其与应用 CI 令牌分开。 - -示例从呈现的 PipelineRun YAML 手动启动测试 CD、推广和生产 CD。替换模板参数，验证镜像映射、身份和工作区，并使用 `kubectl create` 提交。使用 [运行模板](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/run_template.html) 进行其他执行条目。Harbor 事件自动化是额外的集成，不是示例的手动路径的一部分。 - -生产回滚遵循相同的审查边界：选择一个保留的、以前推广的摘要，验证其签名和应用兼容性，并审查 GitOps 更改。数据库和数据迁移需要特定于应用的回滚计划。在目标环境中建立并排练完整的回滚运行手册。配置 [Harbor 标签保留](https://goharbor.io/docs/2.14.0/working-with-projects/working-with-images/create-tag-retention-rules/) 和 [标签不可变性](https://goharbor.io/docs/2.14.0/working-with-projects/working-with-images/create-tag-immutability-rules/)，以确保所需的回滚镜像保持可用。 - -## 选择发布控制 - -推广、审批、凭证门控和镜像接纳解决不同的决策： - -| 决策 | 推荐控制 | -| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| 生产是否使用单独的工件项目？ | 将选定的摘要复制到该项目中，然后更新生产 Git 引用。 | -| 谁授权选定的发布？ | 根据政策，使用 ApprovalTask、生产 Git 合并请求审查或两者。 | -| 谁可以使用生产 Connector？ | 一个专用的发布身份加上入场和 RBAC 限制。当凭证所有者和管道所有者分开时，添加审批门控的代理访问。 | -| 可以部署什么？ | 允许的生产存储库、签名和任何所需的已批准摘要证据的入场政策。 | - -在 [使用 Kyverno 限制工件推广](https://docs.alauda.io/alauda-devops-artifacthub-shim/1.0/catalog/how_to/constrain_artifact_promotion_with_kyverno.html) 中使用核心推广入场规则。规则 1-3 限制推广执行路径。当推广管道在命名空间中维护时，添加规则 4，以控制对该定义的更改。伴随示例未安装这些推广规则或仅限生产存储库的部署策略；平台管理员必须在使用参考设计作为生产控制之前添加它们。 - -推广验证源和目标映射并复制字节。它不会查询 CI 以确定镜像是否通过。审批者必须将摘要与受信任的构建、扫描和测试证据关联。示例验证镜像映射是否首先，源是否使用 SHA-256 摘要，存储库和发布标签格式是否与配置的工作流匹配。可选的签名映射必须引用相同的镜像摘要。 - -### 添加审批节点 - -在 `approvers` 中使用 ACP 组资源名称，而不是组的显示名称或个人名称。以下是任务片段；用实际资源名称替换示例组： - -```yaml -- name: wait-for-approval - taskRef: - apiVersion: openshift-pipelines.org/v1alpha1 - kind: ApprovalTask - timeout: "24h" - params: - - name: approvers - value: - - group:release-managers - - name: numberOfApprovalsRequired - value: "1" - - name: description - value: "批准生产中的推广" -``` - -PipelineRun 和任务超时预算必须包括审批前的工作、整个审批窗口和审批后的工作。保持审批者组与允许启动或修改发布运行的身份分开。使用 [手动审批门](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/manual_approval_gate.html) 进行审批权限、组响应和超时配置。在对象被移除之前，单独保留 ApprovalTask 响应。 - -审批者可以在控制台或通过 `kubectl` 检查待处理的工作。可选示例 `promotion/optional/console-approver.yaml` 提供了自定义控制台角色和组绑定；在应用之前请检查其范围。可以使用目录的 `send-mail` 任务发送审批通知。电子邮件地址、SMTP 配置和凭证必须单独配置；示例未集成该通知步骤。 - -客户变更管理系统集成不在本系列之内。可用的构建块是审批节点和 [传入 Webhooks](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/incoming_webhooks.html)。单独定义该集成的映射和审计合同。 - -### 在审批后门控生产 Connector - -将生产 Connector 及其 Secret 保留在项目成员无法创建 Pods 或运行任意管道的命名空间中。Pod 可以在其自己的命名空间中挂载 Secret，而无需单独的 Secret 读取授权检查。因此，在带有凭证的命名空间中创建 Pods 或 PipelineRuns 的权限是凭证边界。 - -示例发布 ServiceAccount `shop-release` 读取源 Connector，并从 `platform-connectors` 挂载生产 Connector。其现有权限在 `sample-app/promotion/standing-access.yaml` 中。使用 RBAC 进行产品指南中描述的跨命名空间代理权限。 - -审批门控使用两个全局安装功能标志。按以下顺序推出它们： - -1. 清点每个未经过审批的挂载 Connector 的身份。准备其读取授权和 `connectors/proxy` 权限，动词为 `*`。对 `connectors/proxy` 的 `get` 授权不足。不要直接授予生产 Connector 的代理访问权限，必须经过审批。 -2. 启用 `enable-connectors-approval`。立即创建所需的 AccessPolicies，包括管理员-Connector 授权和生产审批政策。在启用标志和创建政策之间，不要启动受影响的运行。 -3. 在生产 AccessPolicy 中，配置指定的 `approvers`，并保持与 ApprovalTask 和推广入场政策的一致性。删除任何其他匹配的默认或直接代理授权。 -4. 启用 `enable-connector-proxy-permissions`，这也将代理权限检查应用于请求。 - -通过 `ConnectorsConfig` 设置功能标志。有关完整配置和验证路径，请参阅 [启用代理权限检查和审批门控](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors/how_to/enable_proxy_permissions_and_approval.html)、[AccessPolicy](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors/concepts/access_policy.html) 和 [Skopeo 复制连接器审批](https://docs.alauda.io/alauda-devops-artifacthub-shim/1.0/catalog/how_to/promote_artifacts_with_skopeo_copy.html#connector-approval)。 - -`defaultPermission` 策略具有授权前提条件，并不能替代每个跨命名空间的 RBAC 授权。仅就绪策略并不能建立有效的挂载。验证实际身份、Pod 事件、挂载配置和 AccessRequest 结果。 - -## 签名和验证镜像 - -集中配置 Chains 签名密钥，并仅将公共验证密钥分发给项目。保护签名 Secret 和在其命名空间中创建 Pods 的能力。应用团队不需要访问签名 Secret。 - -示例将签名和证明存储在镜像旁边。Chains 首先使用运行的 ServiceAccount 中匹配的注册凭证。这些凭证必须能够推送到镜像的注册项目。如果缺少这些凭证，请通过 `TektonConfig` 在 Chains 控制器上配置一个集中管理的注册凭证。Chains 不使用 Connector 的 CSI 代理工作区作为其注册凭证。 - -集中凭证由管理员创建，位于 Git 之外。将其限制为 Chains 必须读取和签名的注册项目。在引导项目时，平台团队必须将其源和生产注册项目添加到该凭证的访问权限中。轮换它并限制其 Secret 和命名空间。在维护窗口中应用控制器配置更改，保留已配置的其他容器选项。 - -成功的 PipelineRun 并不能证明存储的签名。检查 TaskRun 签名注释和事件，并独立验证镜像及其证明。这里的接受对象是镜像摘要和复制 TaskRun 的来源；审批历史是单独的证据。 - -```bash -# IMAGE 是选定的 repository@sha256:digest；平台提供 cosign.pub。 -cosign verify --key cosign.pub "$IMAGE" -cosign verify-attestation --key cosign.pub --type slsaprovenance "$IMAGE" -``` - -对于未配置透明日志的离线安装，使用产品的离线验证设置，包括在需要时使用 `--insecure-ignore-tlog=true`。这会跳过外部透明日志检查；保留签名和证明检查。对私有注册表进行身份验证，而不提交登录凭证。 - -如果平台选择一个单独的签名存储库，请集中配置 `storage.oci.repository`，并在验证和 Kyverno 的存储库设置中使用相应的 `COSIGN_REPOSITORY`。在将构建和推广证明组合为相同摘要之前，检查存储和覆盖行为。在推广期间复制构建签名附件是可选的；如果选择，请使用文档中的 `imageMappings` 和 `multiArch: all` 配置。 - -在部署入场时，在审计中启动镜像验证策略，使用示例的 `mutateDigest: false` 设置，并在执行之前审查匹配的镜像和报告。示例的生产镜像列表是明确的：将每个新引导的生产存储库添加到策略中。请参阅 [镜像签名验证](https://docs.alauda.io/alauda-devops-pipelines/4.15/chains/how_to/image_signature_verification.html)。 - -## 在实际执行点检查控制 - -| 工作流中的点 | 检查内容 | 剩余责任 | -| ---------------------------------- | -------------------------------------------------- | -------------------------------------------- | -| 存储库事件和定义解析 | 事件匹配和已审查的定义来源 | 限制可用于提议源代码的凭证。 | -| PipelineRun 入场 | 允许的定义来源和配置的推广路径 | 限制谁可以编辑引用的定义和参数。 | -| TaskRun 或 CustomRun 创建 | 直接运行限制的已批准控制器身份 | 保护自动化身份及其 RBAC。 | -| 审批 | 指定的审批者响应 | 将已批准的摘要与 CI 和测试证据匹配。 | -| 生产注册表写入 | 推广映射和凭证访问 | 控制其他写入者，包括签名身份。 | -| 工作负载入场 | 允许的注册表和所需的签名检查 | 移除绕过政策的直接部署路径。 | -| 保留和清理 | 选定的运行/日志保留 | 导出审批证据并验证归档访问。 | - -使用平台 ClusterPolicies 作为基线，项目 Policies 作为额外限制。限制 PolicyException 的创建或根据平台政策禁用异常。仅解析器类型的允许列表并不能固定目录、存储库、命名空间、版本或定义内容。启用无内联策略时，必须明确处理内联验证异常。 - -## 接受交付工作流 - -仅在隔离的接受项目中替换输入后，从示例运行 `acceptance/01-commit-to-production.sh`。检查是执行操作步骤，而不是声称任意环境已准备就绪。 - -| 检查 | 所需证据 | -| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| CI 完成 | 受信任的 `main` 运行成功；其镜像存储库和摘要与选定的发布输入匹配。 | -| 测试运行选定的镜像 | 比较完整的工作负载镜像引用并验证发布完成。 | -| 推广复制该镜像 | 推广结果报告预期的目标存储库和摘要。 | -| 生产使用推广结果 | GitOps 合并请求已合并，呈现的镜像与目标摘要匹配，工作负载发布完成。仅 `Synced` 可能描述旧版本。 | -| 签名和来源存在 | 两个 cosign 命令在生产镜像上成功。仅签名注释不足以证明。 | -| 入场强制执行所选政策 | 在接受项目中使用受限兼容探针，并区分政策拒绝与 Pod 安全或镜像拉取失败。之后清理探针。 | -| 审批是可归属的 | 在发布记录中保存 ApprovalTask 响应、审批者组成员、选定摘要和相关运行标识符。 | - -在生产之前，解决示例中的显式加固工作：限制 GitOps 写入者的命名空间，保护生产 Git 更改，安装推广核心规则，限制生产镜像源，并限制直接集群写入。不要授予项目成员在包含管理员或发布凭证的命名空间中创建 Pod 的权限。建立本地回滚和政策服务恢复运行手册。 - -继续阅读 [管理平台配置和引导隔离项目](./Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md)，了解此工作流背后的平台配置、项目声明和操作边界。 diff --git a/docs/zh/solutions/Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md b/docs/zh/solutions/Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md deleted file mode 100644 index 61a9ac383..000000000 --- a/docs/zh/solutions/Managing_Platform_Configuration_and_Onboarding_Isolated_Projects_with_Argo_CD_and_Tekton_on_ACP.md +++ /dev/null @@ -1,327 +0,0 @@ ---- -products: - - Alauda Container Platform - - Alauda DevOps -kind: - - Article -ProductsVersion: - - 4.x -id: KB261000025 -sourceSHA: b2c9ad0d6d69c1a51365ba54b787769b62c7ad46619e5cb41db309d3beb2eec6 ---- - -# 使用 Argo CD 和 Tekton 在 ACP 上管理平台配置和入驻隔离项目 - -使用平台 Git 仓库来审查和保留共享配置。使用入驻管道创建项目的命名空间和工具侧资源，然后通过合并请求提出其部署配置。Argo CD 会对 Git 所拥有的对象进行协调；入驻任务会协调它们在外部工具中创建的资源。 - -本文是 [Alauda DevOps 最佳实践](./Alauda_DevOps_Best_Practices_Overview.md) 的平台部分。它假设一个 ACP 项目和每个项目的独立工具侧租户。其配置基线为 Pipelines 4.15、Artifact Hub Shim 1.0、Connectors 1.14 和 GitOps 4.4，适用于兼容的 ACP 安装。共享一个命名空间和一个工具租户的团队需要不同的边界模型。 - -[伴随示例](https://github.com/AlaudaDevops/devops-best-practices-samples) 包含完整的参考文件。诸如 `shop`、`payments`、`platform-connectors` 和 `registry.example.com` 的名称是虚构的。请根据目标环境替换它们、图像占位符、组资源名称、策略身份和加密的 Secret 占位符。 - -## 建立所有权模型 - -将三种类型的仓库分开： - -| 仓库 | 内容 | 所有者 | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------- | -| 平台仓库 | 组件配置、准入政策、加密的管理员凭证、项目声明和平台原生应用定义 | 平台团队 | -| 模板仓库和目录 | 版本化的共享 Pipelines 和 Tasks；初始项目 GitOps 仓库内容 | 平台团队 | -| 项目仓库 | 应用源代码和 `.tekton/`；项目 GitOps 仓库中的环境清单和摘要引用 | 项目团队 | - -运行模板是在项目命名空间中的执行设置。它们与版本化的目录 Pipeline 定义是不同的。将应用清单排除在平台仓库之外，并将平台策略所有权排除在应用仓库之外。 - -```mermaid -flowchart TB - MR[审查平台变更] --> Git[平台仓库] - Git --> Argo[Argo CD] - Argo --> Components[组件设置] - Argo --> Policies[平台政策] - Argo --> Credentials[加密的管理员凭证] - Argo --> Declarations[已发布的项目声明] - Declarations --> Onboard[Tekton 入驻] - Onboard --> Tools[GitLab Harbor Nexus SonarQube] - Onboard --> Namespaces[项目命名空间和身份] - Onboard --> Seed[种子项目 GitOps 仓库] - Onboard --> Registration[提出平台注册 MR] - Registration --> Git - Seed --> ProjectArgo[项目应用] -``` - -为每个资源或字段分配一个所有者。Argo CD 自我修复适用于其跟踪的对象；它不会协调集群中的每个对象或逆转外部工具操作。删除声明并不是自动退役程序。 - -## 在引导之前准备平台 - -根据其产品安装说明安装组件： - -- [Pipelines](https://docs.alauda.io/alauda-devops-pipelines/4.15/install.html)，包括所需的 [PaC 组件](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/install/manage_pac.html) 和 [手动审批门](https://docs.alauda.io/alauda-devops-pipelines/4.15/how_to/manual_approval_gate_operator.html)。 -- [Connectors](https://docs.alauda.io/alauda-devops-connectors/1.14/install/install.html)。 -- [GitOps](https://docs.alauda.io/gitops/4.4/install_gitops/index.html)。 -- [Kyverno](https://docs.alauda.io/container_platform/4.4/security/security_and_compliance/compliance/install.html) 和密封的秘密控制器。在同步策略和 SealedSecrets 之前，必须存在它们的 CRD。 - -管理员创建管理命名空间，示例中的 `platform-connectors`，并在其中安装四个 Connectors 自动创建任务。这些任务是从 Connectors 文档中安装的；它们不是从通用任务目录中获取的。在提交之前，准备好对四个工具的管理员访问权限，并加密目标密封秘密控制器的凭证。 - -在 Git 之外创建 Chains 签名密钥和中央注册凭证。中央注册凭证必须在同步挂载它的组件层之前存在。仅授予其访问 Chains 必须读取和签名的注册项目，并在项目入驻时更新该访问权限。 - -将平台仓库注册到 Argo CD，并为每个项目 GitOps 仓库提供读取访问权限。一个仓库凭证模板可以覆盖批准的 GitLab URL 前缀；必须为每个项目添加更窄的模板。对于应用和 AppProject GitLab 引用，请使用以 `.git` 结尾的仓库 URL。对于应用目标和 AppProject 目标约束，请使用由 Alauda GitOps 注册的集群名称。 - -通过平台创建 ACP 项目，然后再进行入驻。管道导出该项目的清单以供后续注册。将现有项目导入 Git 需要与创建项目相同的审查：项目应用可以稍后修剪该资源。 - -平台管理员负责平台、项目 GitOps 和应用仓库的 webhook 设置和事件交付验证。使用授权管理仓库 webhook 的令牌进行注册，支持控制器管理的 webhook 创建和删除。有关集中管理，请参见 [为 PAC 创建 Git Secret](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/create_git_secret.html)。示例中的开发人员级 GitOps 令牌无法管理 webhook；在接受入驻之前，请完成管理员 webhook 配置并测试真实事件。 - -保持 Harbor 项目私有。根据其任务指南中的项目隔离要求配置 Nexus 匿名访问和 SonarQube 权限。不要仅仅根据单独凭证的存在推断隔离。 - -对于离线环境，在运行管道之前准备本地目录内容、固定工具和基础镜像、依赖库、证书和漏洞数据库。 - -## 决定 18 个平台基线 - -下表标识平台决策及其仓库层。值和详细步骤属于链接的产品文档。这些是管理员管理的建议，成熟度和前提条件由所选版本决定。 - -| # | 决策 | 共享原因 | 层和指导 | -| -- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | 将仓库访问令牌与 webhook 管理分开；使用经过审查的默认分支定义和显式的 GitLab 提供程序 URL。 | 凭证范围和合并前执行信任应保持一致。 | 凭证和项目：[PaC 仓库配置](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/advanced_repository_config.html)。 | -| 2 | 使用 `/test ` 标准化合并请求重试。 | 团队使用一个支持的入口。 | 项目模板：[触发 PAC Pipelines](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/trigger_pipeline.html)。 | -| 3 | 将平台提供的仓库参数与应用输入分开。 | 地址和连接器名称有明确的所有者。 | 项目：[高级仓库配置](https://docs.alauda.io/alauda-devops-pipelines/4.15/pac/how_to/advanced_repository_config.html)。 | -| 4 | 决定 Harbor 事件交接。 | 事件端点和验证需要一致的所有权。 | 组件：[Harbor 事件](https://docs.alauda.io/alauda-devops-pipelines/4.15/triggers/how_to/harbor_events.html)。 | -| 5 | 使用失败告警调度协调和轮换。 | 平台拥有间隔和操作响应。 | 组件：[ScheduledTrigger](https://docs.alauda.io/alauda-devops-pipelines/4.15/triggers/how_to/scheduledtriggers.html)。 | -| 6 | 标准化 EventListener 暴露。 | TLS、路由和 webhook 验证属于平台。 | 组件：[自动暴露规则](https://docs.alauda.io/alauda-devops-pipelines/4.15/triggers/how_to/trigger-wrapper-config.html)。 | -| 7 | 与四个产品任务协调工具侧租户创建。 | 管理员保留工具范围的凭证。 | 凭证和项目：以下工具任务指南。 | -| 8 | 为每个工具定义长期凭证轮换。 | 过期和续订行为因工具而异。 | 组件和凭证：[凭证轮换](https://docs.alauda.io/alauda-devops-connectors/1.14/how_to/automatically_create_connectors_for_a_project.html#credential-rotation)。 | -| 9 | 配置 Chains 签名密钥和镜像验证。 | 平台拥有签名者并分发其公钥。 | 组件、凭证、政策：[签名密钥](https://docs.alauda.io/alauda-devops-pipelines/4.15/chains/configure/signing_key_configuration.html)。 | -| 10 | 在跟踪长期凭证异常时使用连接器代理访问。 | 访问边界和轮换需要中央所有者。 | 凭证：[连接器代理](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors/concepts/connectors_proxy.html) 和 [CSI 驱动程序](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors/concepts/connectors_csi.html)。 | -| 11 | 应用命名空间 Pod 安全性并分开构建命名空间。 | 构建工具和工作负载有不同的特权需求。 | 政策和项目：[受限标准](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/comply_with_pod_security_restricted.html)。 | -| 12 | 安装审批并定义受保护环境组和提升规则。 | 审批所有权是平台控制。 | 组件、项目、政策：[手动审批门](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/manual_approval_gate.html)。 | -| 13 | 建立平台和项目政策层。 | 项目可以添加限制而不削弱平台基线。 | 政策：[约束管道执行](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/constrain_pipeline_execution_with_kyverno.html)。 | -| 14 | 拥有共享的、本地可用的目录。 | 重用和离线内容需要治理。 | 组件：[作者目录资源](https://docs.alauda.io/alauda-devops-artifacthub-shim/1.0/catalog/how_to/author_catalog_resources.html)。 | -| 15 | 发布版本化的中央 Pipelines。 | 项目明确采用经过审查的版本。 | 组件：[集中式管道管理](https://docs.alauda.io/alauda-devops-pipelines/4.15/pipelines/how_to/hub_pipeline_run_template_centralized_management.html)。 | -| 16 | 选择 Pruner 默认值和命名空间覆盖策略。 | 清理影响共享集群历史和容量。 | 组件：[Pruner 配置](https://docs.alauda.io/alauda-devops-pipelines/4.15/pruner/configure/pruner_configuration.html)。 | -| 17 | 定义结果存储、监视范围、身份验证和保留。 | 审计记录需要独立于实时对象的存储。 | 组件：[结果保留](https://docs.alauda.io/alauda-devops-pipelines/4.15/results/configure/retention_policy_configuration.html)。 | -| 18 | 启用指标和操作监控。 | 操作人员需要控制器和执行健康的证据。 | 组件：[指标收集](https://docs.alauda.io/alauda-devops-pipelines/4.15/configure/metrics_collection.html)。 | - -### 将政策范围与定义信任分开 - -使用平台 ClusterPolicies 进行共享控制，使用命名空间 Policies 进行项目特定限制。通过实际提交身份限制直接创建 TaskRun 和 CustomRun；仅凭客户端提供的所有者引用并不是授权边界。列举控制器身份并审查其权限。 - -可选择将 PipelineRun 引用限制为批准的解析器类型。此简化政策仅说明源类型决策；为每个平台系统命名空间调整命名空间排除： - -```yaml -apiVersion: kyverno.io/v1 -kind: ClusterPolicy -metadata: - name: pipelinerun-source-baseline -spec: - background: false - rules: - - name: approved-resolver-only - match: - any: - - resources: - kinds: [tekton.dev/v1/PipelineRun] - operations: [CREATE] - exclude: - any: - - resources: - namespaces: [platform-connectors] - validate: - failureAction: Audit - message: "pipelineRef 必须使用批准的解析器" - deny: - conditions: - all: - - key: "{{ request.object.spec.pipelineRef.resolver || '' }}" - operator: AnyNotIn - value: [cluster, hub, git] -``` - -这并不限制解析器的 URL、目录、命名空间、版本、定义内容或运行时凭证范围。它还会拒绝强制执行的内联 `pipelineSpec`。在为项目仓库启用该限制之前，将示例的内联验证流程转换为目录 Pipeline。根据平台政策限制 PolicyException 的创建或禁用异常。 - -示例中的 `argocd-project-namespace-boundary` 策略通过配置的 Argo CD 身份限制 Role、RoleBinding、ResourceQuota、LimitRange 和 NetworkPolicy 的写入。它允许平台拥有的注册路径，并要求 `allowExistingViolations: false`。为目标集群调整两个 Argo CD 身份，并在依赖于边界之前验证预期的允许和拒绝情况。在每个目标集群上安装并验证该策略，以确保边界适用。 - -Kyverno 的可用性和恢复是平台操作的关注点。准备本地运行手册；本系列不规定在政策服务中断期间集群的写入行为。有关政策设计，请参见 [使用 Tekton 和 Kyverno 的管道政策约束](./Pipeline_Policy_Constraints_with_Tekton_and_Kyverno.md)。 - -## 组织和同步平台仓库 - -示例分为四个所有权层和入驻安装： - -```text -platform-config/ -├── argocd/apps/ # 根和子应用定义 -├── components/ # TektonConfig 和组件选项 -├── policies/ # 平台准入政策 -├── credentials/ # 管理员连接器和密封占位符 -├── projects/ # 声明和审核注册输出 -├── templates/ # 注册渲染模板 -├── onboarding/ # Pipelines、运行模板、调度和 RBAC -└── .tekton/ # 验证和变更项目调度 -``` - -根据其 README 将 `onboarding/` 从示例复制到平台仓库根目录。将仓库以只读方式注册到 Argo CD，并为每个层使用一个子应用。根应用管理这些应用定义。 - -对于部分单例组件配置，使用服务器端应用，以便平台仓库仅拥有指定字段。示例还设置了 `argocd.argoproj.io/compare-options: ServerSideDiff=true`。在同步之前审查生成的差异和操作员的字段所有权。组件层使用 `prune: false`，以便删除片段不会删除单例 TektonConfig。在启用持续自我修复之前，建立组件层在目标环境中的自动同步行为。 - -凭证层不启用自我修复：为目标控制器密封凭证，并计划如何在轮换时更新实时 Secrets 和加密源。其他层可以根据其所有权使用修剪和自我修复。命名空间由入驻创建；不要使用 `CreateNamespace` 添加第二个命名空间创建者。 - -ACP 维护与 ACP 项目关联的 AppProject。注册补丁仅管理预期的仓库和目标字段。与平台管理的条目协调有效目标，并使用准入边界进行对象类型限制。不要仅依赖应用的同步状态来证明部署边界。 - -仔细审查删除。修剪注册的 ACP 项目可能会删除其同名命名空间及其 Secrets、Connectors 和 Repository 对象。它不会逆转工具侧创建或删除每个构建、交付或环境命名空间。退役需要单独批准的程序。 - -### 在合并之前验证更改 - -平台和项目 GitOps 模板都包含 `.tekton/validate.yaml`，该文件组合了目录 `git-clone` 和 `run-script` 任务。将其工具镜像替换为包含所需 shell 和 Kustomize 命令的本地可用镜像。在第一次合并请求运行之前建立其 webhook。通过默认分支定义来源，验证定义的更改在进入该分支后首次执行。 - -验证每个由应用拥有的目录，并将新目录添加到验证路径中。使用 `/test validate` 重新运行合并请求检查。YAML 解析和 Kustomize 渲染不会验证 CRD 准入行为；使用目标模式和隔离项目进行该接受步骤。 - -## 声明项目并运行入驻 - -声明是示例架构，而不是 ACP API。管道验证其支持的命名约定。完整的 `shop` 声明包括以下字段；使用示例的完整文件： - -```yaml -name: shop -platformProject: shop -owners: - - shop-platform-owners -environments: [test, prod] -tools: [gitlab, harbor, nexus, sonarqube] -approvers: - prod: group:release-managers -imagePullFrom: [] -namespaces: - workloads: [shop, shop-test, shop-prod] - build: shop-build - delivery: shop-cd -gitlab: - group: shop - subgroups: [apps, gitops] -harbor: - projects: [shop, shop-prod] -nexus: - repositories: - - name: shop-maven - format: maven2 - type: hosted - - name: shop-npm - format: npm - type: hosted -sonarqube: - project: shop -``` - -`owners` 包含没有 `group:` 前缀的 ACP 组资源名称；审批条目使用 `group:`。控制台显示名称不是资源名称。组成员资格的更改属于组管理，而不是在每个声明中编辑个人名称。 - -提交声明、项目特定的入驻权限和调度通过平台合并请求。确认声明和入驻应用已同步；在使用手动同步策略时手动同步它们。然后检查调度结果和每个子入驻运行。成功的合并或调度并不单独建立完整的项目准备状态。 - -示例在合并后调度更改的声明。路径过滤器也可以允许没有相关声明更改的运行；调度程序负责选择实际声明。删除的声明被跳过，而不是被解释为删除项目的指令。 - -### 理解七个入驻阶段 - -| 阶段 | 工作 | 所有者或机制 | -| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -| 1 | 导出现有的 ACP 项目而不带运行时元数据；创建或协调标记命名空间和交付身份。工作负载使用受限的 Pod 安全性；构建命名空间是分开的。 | 示例编排和 Kubernetes API | -| 2 | 创建 GitLab 租户组和项目访问令牌；为 GitOps 交付创建一个单独的写入连接器。 | GitLab 自动创建任务 | -| 3 | 创建私有源和生产 Harbor 项目，分发镜像拉取配置，并为发布创建单独的源读取和生产写入连接器。 | Harbor 自动创建任务 | -| 4 | 创建 Nexus 仓库和范围用户，然后写入项目连接器。 | Nexus 自动创建任务 | -| 5 | 创建 SonarQube 用户、令牌和项目权限模板，然后写入连接器。 | SonarQube 自动创建任务 | -| 6 | 种子空项目 GitOps 仓库并创建其 PaC 仓库和访问 Secret。单独完成和验证 webhook 配置。 | 示例模板播种和 PaC 资源 | -| 7 | 渲染项目应用、AppProject 补丁、所有者和连接器绑定以及导出的 ACP 项目。打开平台注册合并请求。 | 单独的 `gitops-repo-update` PipelineRun | - -注册步骤提出 Git 更改，而不是直接应用 Argo CD 资源。审查整个差异，包括 RBAC 和目标更改。为父运行和子运行保留足够的执行容量：等待的父运行仍然保留其 Pod 资源。取消和清理必须考虑独立创建的子运行。 - -管道在管理命名空间中运行，使用管理员连接器。在那里创建 Pods 或 PipelineRuns 的权限实际上是对这些凭证的访问，即使没有 API 权限读取 Secrets。将该命名空间和入驻身份限制为平台自动化和管理员。 - -### 重用产品任务 - -这四个任务具有不同的参数和轮换行为。阅读它们的安装、访问和前提条件说明： - -- [GitLab 租户组和连接器](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors-gitlab/how_to/using_gitlab_connector_automatic_creation_task.html)。 -- [Harbor 资源和连接器](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors-harbor/how_to/using_harbor_connector_automatic_creation_task.html)。 -- [Nexus 资源和连接器](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors-nexus/how_to/using_nexus_connector_automatic_creation_task.html)。 -- [SonarQube 租户和连接器](https://docs.alauda.io/alauda-devops-connectors/1.14/connectors-sonarqube/how_to/using_sonarqube_connector_automatic_creation_task.html)。 - -将目标 `connector` 设置为 `namespace/name`。明确设置 GitLab 访问级别：项目访问令牌和 GitOps 写入者有不同的职责。在示例中，项目访问使用 `api` 和 `read_repository`；写入者还使用 `write_repository`。连接器 CSI挂载使用 `connectors` 属性，并包含命名空间。 - -示例仅使用显式授权的 ServiceAccount 向当前集群写入。对于跨集群应用，请遵循每个任务的 Kubernetes 连接器和 `kubeconfig` 工作区说明。不要假设管理命名空间的默认 ServiceAccount 具有所需的写入权限。 - -替代产品工作流从命名空间事件创建项目连接器：[为项目自动创建连接器](https://docs.alauda.io/alauda-devops-connectors/1.14/how_to/automatically_create_connectors_for_a_project.html)。如果选择该路径，请为每个租户和资源分配一个创建者和轮换所有者。避免两个独立的协调者管理相同的凭证。 - -## 注册仓库并验证事件 - -在每个 PaC 仓库上设置自我管理的提供程序 URL 和经过审查的定义源。以下片段省略凭证数据；通过批准的凭证路径创建其引用的 Secret： - -```yaml -apiVersion: pipelinesascode.tekton.dev/v1alpha1 -kind: Repository -metadata: - name: shop-gitops - namespace: shop -spec: - url: https://git.example.com/shop/gitops/config - git_provider: - type: gitlab - url: https://git.example.com - secret: - name: shop-gitops-auth - webhook_secret: - name: shop-gitops-auth - settings: - pipelinerun_provenance: default_branch -``` - -明确设置提供程序 URL，以便完成请求和仓库令牌使用预期的 GitLab 实例。PaC 仓库 URL 与 Argo CD 使用的 `.git` URL 不同。`gitops/config` 是 `gitops` 子组下的一个仓库，而不是与该子组名称冲突的仓库路径。 - -示例的项目 GitOps 令牌为开发人员级别，需要管理员管理的 webhook 设置。验证新事件及其结果运行。在仓库退役后保持 webhook 管理凭证可用，并检查剩余的代码平台 webhook。应用的仓库属于构建命名空间，CI 在其中执行。 - -## 深思熟虑地协调和轮换 - -使用相同支持参数的重复运行进行协调。不要将连接器 `Ready=True` 等同于未过期、可用的工具令牌；在轮换之前和之后执行授权的工具请求或工作负载操作。 - -| 更改 | 所需操作 | -| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -| 支持的声明字段更改 | 审查任务特定的重建和轮换影响，然后协调项目。 | -| 添加新环境 | 通过项目合并请求添加其 GitOps 目录和验证路径，以及更改声明。 | -| 模板更改 | 分别提出对现有项目仓库的更新。仅将副本播种到空仓库中。 | -| 凭证到期 | 在到期减去安全边际的时间间隔内运行相关任务；在失败时发出警报并重试。 | -| 凭证没有到期 | 根据政策要求的时间间隔进行轮换；明确选择任务的刷新行为。 | - -示例支持的 GitLab 子组为 `apps` 和 `gitops`。更改该约定需要经过审查的管道更改，而不仅仅是声明编辑。工具侧身份更改可以重新创建帐户或凭证；在更改名称或项目集之前检查产品任务的合同。 - -不要重叠同一租户的运行。安排轮换在活动管道窗口之外，并在当前凭证过期之前监控失败的运行。CSI 工作负载令牌的发放与轮换工具的长期凭证是分开的。请参阅任务指南以获取到期恢复；定义本地恢复程序，而不是依赖未观察到的自然到期路径。 - -如果启用连接器审批，请为每个受影响的工作负载准备授权，启用 `enable-connectors-approval`，立即创建所需的 AccessPolicies，然后启用 `enable-connector-proxy-permissions`。示例中的可选管理员 AccessPolicy 被排除在默认 Kustomization 之外，仅在启用该功能后应用。使用 RBAC 进行文档化的跨命名空间授权，并保持审批门控的生产连接器不直接授予代理权限。有关完整的发布边界，请参见 [交付文章](./From_Commit_to_Production_on_ACP.md#gate-the-production-connector-after-approval)。 - -## 接受项目边界 - -| 边界 | 必须证明的内容 | -| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 命名空间和 Pod 安全性 | 工作负载命名空间具有预期的标签；构建和交付使用其单独的命名空间和身份。 | -| 部署范围 | 有效的 AppProject 目标和平台准入仅允许预期的项目部署路径。使用实际的 Argo CD 身份测试禁止的 RBAC 和配额写入。 | -| 工具访问 | GitLab、Harbor、Nexus 和 SonarQube 授权与租户匹配。在进行负面跨项目测试之前，使用正面控制。 | -| 凭证访问 | 项目用户无法在管理员或签名命名空间中创建 Pods 或运行。在单独的清单中盘点镜像拉取 Secrets、PaC 克隆凭证和中央 Chains 凭证。 | -| 事件路由 | 新的仓库事件或合并请求重试会在预期的命名空间中产生预期的运行。 | -| 轮换 | 成功的非重叠运行更新预期的凭证，并且授权操作在之后正常工作。 | - -在隔离的验收项目中运行示例中的 `acceptance/02-platform-and-onboarding.sh`。其伴随交付脚本在第一次应用构建后验证镜像路径。检查每个子入驻运行、四个连接器、播种的仓库、注册合并请求和应用。初始占位符摘要不可部署；工作负载健康状况在第一次真实部署后跟随。 - -对于跨项目镜像拒绝，首先验证确切的镜像存在并可以在其自己的项目中拉取。然后测试未授权项目，区分 `unauthorized` 与 `not found` 和 Pod 安全性拒绝，并在使用存在于该项目中的镜像的相反方向重复。检查后删除临时探测资源。 - -仅在可接受项目中的一次性资源上测试自我修复。记录其 UID 和恢复清单，执行批准的更改，并确认使用不同的 UID 重新创建。如果检查失败，则恢复。这与证明操作员管理的组件层的持续自动协调是分开的。 - -## 保留审计记录并计划恢复 - -选择一种清理机制并在启用之前审查其范围。根据全局和命名空间配置指南使用基于事件的 Pruner；在迁移时禁用较旧的定期机制。在目标环境中验证每种选择的保留模式，以确保其可以删除共享运行历史。 - -使用外部 PostgreSQL 和文档化的日志存储来保存结果。定义监视范围、身份验证和一个保留策略作为参考配置。通过结果 API 验证读取授权，而不是从 Kubernetes 资源可见性推断。清理之前单独保留审批响应，以免清理删除 ApprovalTask 对象。 - -在启用结果观察者之前确定其范围：默认观察可能会影响跨命名空间的已完成运行，并添加 `results.tekton.dev/*` 最终处理程序。禁用归档不会删除已经存在的最终处理程序。在删除之前遵循产品恢复程序，并在集群对象被修剪后将外部结果存储视为审计源。有关 S3 存储和结果保留的更多信息，请参见 [S3 存储](https://docs.alauda.io/alauda-devops-pipelines/4.15/results/configure/s3_storage_configuration.html) 和 [结果保留](https://docs.alauda.io/alauda-devops-pipelines/4.15/results/configure/retention_policy_configuration.html)。 - -Git 并不能替代凭证和外部数据的备份。在平台重建之前，平台团队必须准备并演练这些依赖项的恢复： - -1. 兼容的平台组件、Kyverno 和密封秘密 CRD 和控制器。 -2. 密封秘密解密密钥，或新控制器的重新密封凭证。 -3. Chains 签名密钥和中央注册凭证；在镜像准入时协调任何验证密钥更改。 -4. 管理命名空间和安装的自动创建任务。 -5. Argo CD 仓库访问和项目仓库凭证模板，以及 PaC 访问和 webhook 配置。 - -在准备好这些依赖项后，同步平台层，运行入驻声明的项目，审查注册更改，并完成验收检查。这是一个依赖项大纲；完整的空集群或第二集群恢复运行手册必须在目标环境中进行演练。 - -在生产之前，完成示例的加固工作：将合并前验证与管理员凭证隔离，缩小用于项目注册的 AppProject，保护 GitOps 写入者的命名空间，安装提升核心规则，并限制生产镜像源。在 Git 审查的同时限制直接集群写入。模板升级、退役、容量规划、离线包分发和客户变更管理集成需要单独的操作程序。 - -继续阅读 [从提交到生产](./From_Commit_to_Production_on_ACP.md)，以使用入驻项目的构建、测试、提升和生产 GitOps 路径。