diff --git a/docs/docs/15-concepts.md b/docs/docs/15-concepts.md index 2f0c8b8e3..536c3a9be 100644 --- a/docs/docs/15-concepts.md +++ b/docs/docs/15-concepts.md @@ -16,6 +16,11 @@ RBAC rules are also defined at the project level and project administrators may use projects to define policies, such as whether a **stage** is eligible for automatic promotions of new **freight**. +:::note +For more information on the Project Resource types, promotion policies, +and namespace adoption refer to [Managing Projects](./30-how-to-guides/40-managing-projects.md) in the How-to guides. +::: + ### What is a Stage? When you hear the term “environment”, what you envision will depend @@ -72,84 +77,6 @@ A **promotion** is a request to move a piece of freight into a specified stage. Each of Kargo's fundamental concepts maps directly onto a custom Kubernetes resource type. -### `Project` Resources - -Each Kargo project is represented by a cluster-scoped Kubernetes resource of -type `Project`. Reconciliation of such a resource effects all boilerplate -project initialization, including the creation of a specially-labeled -`Namespace` with the same name as the `Project`. All resources belonging to a -given `Project` should be grouped together in that `Namespace`. - -A minimal `Project` resource looks like the following: - -```yaml -apiVersion: kargo.akuity.io/v1alpha1 -kind: Project -metadata: - name: kargo-demo -``` - -:::note -Deletion of a `Project` resource results in the deletion of the corresponding -`Namespace`. For convenience, the inverse is also true -- deletion of a -project's `Namespace` results in the deletion of the corresponding `Project` -resource. -::: - -:::info -There are compelling advantages to using `Project` resources instead of -permitting users to create `Namespace` resources directly: - -* The required label indicating a `Namespace` is a Kargo project cannot be - forgotten or misapplied. - -* Users can be granted permission to indirectly create `Namespace` resources for - Kargo projects _only_ without being granted more general permissions to create - _any_ new `Namespace` directly. - -* Boilerplate configuration is automatically created at the time of `Project` - creation. This includes things such as project-level RBAC resources and - `ServiceAccount` resources. -::: - -:::info -In future releases, the team also expects to also aggregate project-level status -and statistics in `Project` resources. -::: - -#### Promotion Policies - -A `Project` resource can additionally define project-level configuration. At -present, this only includes **promotion policies** that describe which `Stage`s -are eligible for automatic promotion of newly available `Freight`. - -:::note -Promotion policies are defined at the project-level because users with -permission to update `Stage` resources in a given project `Namespace` may _not_ -have permission to create `Promotion` resources. Defining promotion policies at -the project-level therefore restricts such users from enabling automatic -promotions for a `Stage` to which they may lack permission to promote to -manually. It leaves decisions about eligibility for auto-promotion squarely in -the hands of someone like a "project admin." -::: - -In the example below, the `test` and `uat` `Stage`s are eligible for automatic -promotion of newly available `Freight`, but any other `Stage`s in the `Project` -are not: - -```yaml -apiVersion: kargo.akuity.io/v1alpha1 -kind: Project -metadata: - name: kargo-demo -spec: - promotionPolicies: - - stage: test - autoPromotionEnabled: true - - stage: uat - autoPromotionEnabled: true -``` - ### `Stage` Resources Each Kargo stage is represented by a Kubernetes resource of type `Stage`. diff --git a/docs/docs/30-how-to-guides/40-managing-projects.md b/docs/docs/30-how-to-guides/40-managing-projects.md index ca4a6f528..23e38f898 100644 --- a/docs/docs/30-how-to-guides/40-managing-projects.md +++ b/docs/docs/30-how-to-guides/40-managing-projects.md @@ -5,38 +5,120 @@ sidebar_label: Managing Projects # Managing Projects -### Namespace Creation and Adoption in Kargo Projects +Each Kargo project is represented by a cluster-scoped Kubernetes resource of +type `Project`. Reconciliation of such a resource effects all boilerplate +project initialization, including the creation of a specially-labeled +`Namespace` with the same name as the `Project`. All resources belonging to a +given `Project` should be grouped together in that `Namespace`. -When a new Kargo `Project` is created, it automatically generates a corresponding Kubernetes `namespace`. -In scenarios where specific configuration requirements are needed, Kargo offers an adoption feature for -pre-existing namespaces. +A minimal `Project` resource looks like the following: -Kargo can adopt namespaces that you create beforehand, if they are labeled -with `kargo.akuity.io/project: "true"`. -This allows you to pre-configure namespaces with necessary labels and resources. +```yaml +apiVersion: kargo.akuity.io/v1alpha1 +kind: Project +metadata: +name: kargo-demo +``` + +:::note +Deletion of a `Project` resource results in the deletion of the corresponding +`Namespace`. For convenience, the inverse is also true -- deletion of a +project's `Namespace` results in the deletion of the corresponding `Project` +resource. +::: + +:::info +There are compelling advantages to using `Project` resources instead of +permitting users to create `Namespace` resources directly: + +* The required label indicating a `Namespace` is a Kargo project cannot be +forgotten or misapplied. + +* Users can be granted permission to indirectly create `Namespace` resources for +Kargo projects _only_ without being granted more general permissions to create +_any_ new `Namespace` directly. + +* Boilerplate configuration is automatically created at the time of `Project` +creation. This includes things such as project-level RBAC resources and +`ServiceAccount` resources. +::: + +:::info +In future releases, the team also expects to also aggregate project-level status +and statistics in `Project` resources. +::: + +### Promotion Policies + +A `Project` resource can additionally define project-level configuration. At +present, this only includes **promotion policies** that describe which `Stage`s +are eligible for automatic promotion of newly available `Freight`. -* Define the `namespace` in your YAML manifest, adding any required labels -and resources. Ensure the label `kargo.akuity.io/project: "true"` is applied to the `namespace`. -* When using a YAML file, list the `namespace` definition above the Kargo `Project` resource to ensure it is created first. +:::note +Promotion policies are defined at the project-level because users with +permission to update `Stage` resources in a given project `Namespace` may _not_ +have permission to create `Promotion` resources. Defining promotion policies at +the project-level therefore restricts such users from enabling automatic +promotions for a `Stage` to which they may lack permission to promote to +manually. It leaves decisions about eligibility for auto-promotion squarely in +the hands of someone like a "project admin." +::: -In the following example, the `namespace` is labeled with `eso.example.com.au: cluster-secret-store-alpha` previously. -When the Kargo `Project` is created, it automatically adopts this pre-existing `namespace`. +In the example below, the `test` and `uat` `Stage`s are eligible for automatic +promotion of newly available `Freight`, but any other `Stage`s in the `Project` +are not: +```yaml +apiVersion: kargo.akuity.io/v1alpha1 +kind: Project +metadata: +name: kargo-demo +spec: +promotionPolicies: +- stage: test +autoPromotionEnabled: true +- stage: uat +autoPromotionEnabled: true ``` + +## Namespace Adoption + +To ensure compliance with governance policies, you may need +to pre-configure namespaces with specific labels or annotations +required by your organization's policy agents. + +Kargo supports the adoption of pre-existing namespaces that are +labeled with `kargo.akuity.io/project: "true"`. This enables you +to pre-configure namespaces according to your organization's requirements. + +For example, if your policy agent mandates that all namespaces include +a label identifying the internal organization responsible for them, +you can define the `namespace` in your YAML manifest with +the necessary labels and resources: + +* Add the label `kargo.akuity.io/project: "true"` to your `namespace` definition. +* Ensure that in your YAML file, the `namespace` definition is listed above the +Kargo `Project` resource to allow it to be created first. + +In this example, the `namespace` is pre-labeled to indicate the responsible +internal organization. When the Kargo `Project` is created, it automatically +adopts this pre-existing `namespace`. + +```yaml apiVersion: v1 kind: Namespace metadata: - name: kargo-example - labels: + name: kargo-example +labels: kargo.akuity.io/project: "true" - eso.example.com: cluster-secret-store + org.example.com: responsible-org --- apiVersion: kargo.akuity.io/v1alpha1 kind: Project metadata: name: kargo-example spec: - # Project specifications go here +# Project specifications go here ``` -This process allows the Kargo `Project` to recognize and use your pre-configured `namespace` without needing further updates or intervention. +This setup allows the Kargo `Project` to recognize and utilize your pre-configured `namespace` seamlessly, aligning with your compliance requirements without additional updates.