From c098015e3a93ae38563c8663c405ab77a6e9d60d Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Tue, 8 Oct 2024 22:54:53 +0530 Subject: [PATCH 1/8] init Signed-off-by: Faeka Ansari --- docs/docs/30-how-to-guides/40-managing-projects.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 docs/docs/30-how-to-guides/40-managing-projects.md diff --git a/docs/docs/30-how-to-guides/40-managing-projects.md b/docs/docs/30-how-to-guides/40-managing-projects.md new file mode 100644 index 000000000..b72acbd9e --- /dev/null +++ b/docs/docs/30-how-to-guides/40-managing-projects.md @@ -0,0 +1,6 @@ +--- +description: Learn how to manage Projects +sidebar_label: Managing Projects +--- + +# Managing Projects From ce5b52d7c04112b7ced76b7d670c61db6dfd1869 Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Mon, 28 Oct 2024 17:00:30 +0530 Subject: [PATCH 2/8] add docs Signed-off-by: Faeka Ansari --- .../30-how-to-guides/40-managing-projects.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) 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 b72acbd9e..ca4a6f528 100644 --- a/docs/docs/30-how-to-guides/40-managing-projects.md +++ b/docs/docs/30-how-to-guides/40-managing-projects.md @@ -4,3 +4,39 @@ sidebar_label: Managing Projects --- # Managing Projects + +### Namespace Creation and Adoption in Kargo Projects + +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. + +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. + +* 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. + +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`. + +``` +apiVersion: v1 +kind: Namespace +metadata: + name: kargo-example + labels: + kargo.akuity.io/project: "true" + eso.example.com: cluster-secret-store +--- +apiVersion: kargo.akuity.io/v1alpha1 +kind: Project +metadata: + name: kargo-example +spec: + # Project specifications go here +``` + +This process allows the Kargo `Project` to recognize and use your pre-configured `namespace` without needing further updates or intervention. From f70029c5c2d451b7cc32117b959c5d412e52c8e0 Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Tue, 29 Oct 2024 18:23:16 +0530 Subject: [PATCH 3/8] include project overview, update example Signed-off-by: Faeka Ansari --- docs/docs/15-concepts.md | 83 +------------ .../30-how-to-guides/40-managing-projects.md | 116 +++++++++++++++--- 2 files changed, 104 insertions(+), 95 deletions(-) diff --git a/docs/docs/15-concepts.md b/docs/docs/15-concepts.md index 3932d703e..5ab7c7d5d 100644 --- a/docs/docs/15-concepts.md +++ b/docs/docs/15-concepts.md @@ -22,6 +22,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 @@ -80,84 +85,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. From d3be0cefa6125c24528c61e5cb82a14fad2c6af3 Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Wed, 30 Oct 2024 03:10:09 +0530 Subject: [PATCH 4/8] rename: working with projects Signed-off-by: Faeka Ansari --- ...{40-managing-projects.md => 11-working-with-projects.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename docs/docs/30-how-to-guides/{40-managing-projects.md => 11-working-with-projects.md} (97%) diff --git a/docs/docs/30-how-to-guides/40-managing-projects.md b/docs/docs/30-how-to-guides/11-working-with-projects.md similarity index 97% rename from docs/docs/30-how-to-guides/40-managing-projects.md rename to docs/docs/30-how-to-guides/11-working-with-projects.md index 23e38f898..c0e878706 100644 --- a/docs/docs/30-how-to-guides/40-managing-projects.md +++ b/docs/docs/30-how-to-guides/11-working-with-projects.md @@ -1,9 +1,9 @@ --- -description: Learn how to manage Projects -sidebar_label: Managing Projects +description: Learn how to work effectively with Projects +sidebar_label: Working with Projects --- -# Managing Projects +# Working with Projects Each Kargo project is represented by a cluster-scoped Kubernetes resource of type `Project`. Reconciliation of such a resource effects all boilerplate From 70c80f59c88c49f03af3eae623549a7af3061bea Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Wed, 6 Nov 2024 17:21:52 +0530 Subject: [PATCH 5/8] addrss reviews by @krancour Signed-off-by: Faeka Ansari --- docs/docs/15-concepts.md | 4 +- .../11-working-with-projects.md | 43 +++++++------------ 2 files changed, 18 insertions(+), 29 deletions(-) diff --git a/docs/docs/15-concepts.md b/docs/docs/15-concepts.md index 5ab7c7d5d..677fff62a 100644 --- a/docs/docs/15-concepts.md +++ b/docs/docs/15-concepts.md @@ -23,8 +23,8 @@ 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. +For technical information on the corresponding `Project` resource +type, refer to [Working with Projects](./30-how-to-guides/11-working-with-projects.md). ::: ### What is a Stage? diff --git a/docs/docs/30-how-to-guides/11-working-with-projects.md b/docs/docs/30-how-to-guides/11-working-with-projects.md index c0e878706..0ac331145 100644 --- a/docs/docs/30-how-to-guides/11-working-with-projects.md +++ b/docs/docs/30-how-to-guides/11-working-with-projects.md @@ -43,12 +43,7 @@ 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 +## Promotion Policies A `Project` resource can additionally define project-level configuration. At present, this only includes **promotion policies** that describe which `Stage`s @@ -83,26 +78,22 @@ 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. +At times, `Namespace`s may require specific configuration to +comply with regulatory or organizational requirements. To +account for this, Kargo supports the adoption of pre-existing +`Namespace`s that are labeled with `kargo.akuity.io/project: "true"`. +This enables you pre-configure such `Namespace`s according to your +own 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. +:::info +`kargo.akuity.io/project: "true"` label serves as a safeguard, +ensuring that only designated namespaces can be adopted as Kargo `Project`s, +thereby preventing the inadvertent integration of non-Project namespaces. +::: -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`. +For example, if your policy agent mandates that all `Namespace`s include +a label identifying the internal organization responsible for them, you +can define such a `Namespace` directly as in the following example: ```yaml apiVersion: v1 @@ -118,7 +109,5 @@ kind: Project metadata: name: kargo-example spec: -# Project specifications go here + # Project specifications go here ``` - -This setup allows the Kargo `Project` to recognize and utilize your pre-configured `namespace` seamlessly, aligning with your compliance requirements without additional updates. From 8fc3cf363ad13969045bbb4143ab00c3fb84df38 Mon Sep 17 00:00:00 2001 From: Kent Rancourt Date: Wed, 6 Nov 2024 09:38:22 -0500 Subject: [PATCH 6/8] Apply suggestions from code review minor tweaks Signed-off-by: Kent Rancourt --- .../11-working-with-projects.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/docs/30-how-to-guides/11-working-with-projects.md b/docs/docs/30-how-to-guides/11-working-with-projects.md index 0ac331145..2ce4168e1 100644 --- a/docs/docs/30-how-to-guides/11-working-with-projects.md +++ b/docs/docs/30-how-to-guides/11-working-with-projects.md @@ -82,32 +82,29 @@ At times, `Namespace`s may require specific configuration to comply with regulatory or organizational requirements. To account for this, Kargo supports the adoption of pre-existing `Namespace`s that are labeled with `kargo.akuity.io/project: "true"`. -This enables you pre-configure such `Namespace`s according to your +This enables pre-configuring such `Namespace`s according to your own requirements. :::info -`kargo.akuity.io/project: "true"` label serves as a safeguard, -ensuring that only designated namespaces can be adopted as Kargo `Project`s, -thereby preventing the inadvertent integration of non-Project namespaces. +Requiring a `Namespace` to have the `kargo.akuity.io/project: "true"` label to be eligible for adoption by a new `Project` is intended to prevent accidental or willful hijacking of an existing `Namespace`. ::: -For example, if your policy agent mandates that all `Namespace`s include -a label identifying the internal organization responsible for them, you -can define such a `Namespace` directly as in the following example: +The following example demonstrates adoption of a `Namespace` that's been +pre-configured with with a label unrelated to Kargo: ```yaml apiVersion: v1 kind: Namespace metadata: - name: kargo-example + name: example labels: kargo.akuity.io/project: "true" - org.example.com: responsible-org + example.com/org: platform-eng --- apiVersion: kargo.akuity.io/v1alpha1 kind: Project metadata: - name: kargo-example + name: example spec: # Project specifications go here ``` From 036561478dd8fd92b55d84ea7ca0c924057af464 Mon Sep 17 00:00:00 2001 From: Kent Rancourt Date: Wed, 6 Nov 2024 09:43:27 -0500 Subject: [PATCH 7/8] Apply suggestions from code review Signed-off-by: Kent Rancourt --- .../11-working-with-projects.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/docs/30-how-to-guides/11-working-with-projects.md b/docs/docs/30-how-to-guides/11-working-with-projects.md index 2ce4168e1..2a07d91ef 100644 --- a/docs/docs/30-how-to-guides/11-working-with-projects.md +++ b/docs/docs/30-how-to-guides/11-working-with-projects.md @@ -69,11 +69,11 @@ kind: Project metadata: name: kargo-demo spec: -promotionPolicies: -- stage: test -autoPromotionEnabled: true -- stage: uat -autoPromotionEnabled: true + promotionPolicies: + - stage: test + autoPromotionEnabled: true + - stage: uat + autoPromotionEnabled: true ``` ## Namespace Adoption @@ -96,15 +96,15 @@ pre-configured with with a label unrelated to Kargo: apiVersion: v1 kind: Namespace metadata: - name: example + name: example labels: - kargo.akuity.io/project: "true" - example.com/org: platform-eng + kargo.akuity.io/project: "true" + example.com/org: platform-eng --- apiVersion: kargo.akuity.io/v1alpha1 kind: Project metadata: - name: example + name: example spec: - # Project specifications go here + # ... ``` From ddacc27f857fd6910363ddd64955d760ddc874a0 Mon Sep 17 00:00:00 2001 From: Kent Rancourt Date: Wed, 6 Nov 2024 09:49:16 -0500 Subject: [PATCH 8/8] Apply suggestions from code review Signed-off-by: Kent Rancourt --- docs/docs/30-how-to-guides/11-working-with-projects.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/30-how-to-guides/11-working-with-projects.md b/docs/docs/30-how-to-guides/11-working-with-projects.md index 2a07d91ef..7e3ca6e46 100644 --- a/docs/docs/30-how-to-guides/11-working-with-projects.md +++ b/docs/docs/30-how-to-guides/11-working-with-projects.md @@ -17,7 +17,7 @@ A minimal `Project` resource looks like the following: apiVersion: kargo.akuity.io/v1alpha1 kind: Project metadata: -name: kargo-demo + name: example ``` :::note @@ -67,7 +67,7 @@ are not: apiVersion: kargo.akuity.io/v1alpha1 kind: Project metadata: -name: kargo-demo + name: example spec: promotionPolicies: - stage: test