Skip to content

Commit

Permalink
include project overview, update example
Browse files Browse the repository at this point in the history 
Signed-off-by: Faeka Ansari <[email protected]>
  • Loading branch information
@fykaa
fykaa committed Oct 29, 2024
1 parent ed71b5c commit 47d6724
Show file tree
Hide file tree
Showing 2 changed files with 104 additions and 95 deletions.
83 changes: 5 additions & 78 deletions docs/docs/15-concepts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`.
Expand Down
116 changes: 99 additions & 17 deletions docs/docs/30-how-to-guides/40-managing-projects.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

0 comments on commit 47d6724

Please sign in to comment.