Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(backport release-1.1): docs: manual rolebindings for global namespaces #3127

Merged
merged 1 commit into from
Dec 12, 2024
Merged

chore(backport release-1.1): docs: manual rolebindings for global namespaces #3127

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 45 additions & 7 deletions docs/docs/30-how-to-guides/20-managing-credentials.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_label: Managing Credentials

# Managing Credentials

To manage the progression of freight from stage to stage, Kargo will often
To manage the progression of Freight from Stage to Stage, Kargo will often
require read/write permissions on private GitOps repositories and read-only
permissions on private container image and/or Helm chart repositories.

Expand Down Expand Up @@ -106,6 +106,50 @@ Refer to
[the advanced section of the installation guide](./10-installing-kargo.md#advanced-installation)
for more details.

:::note
Operators must manually ensure Kargo controllers receive read-only access
to `Secret`s in the designated namespaces. For example, if `kargo-global-creds`
is designated as a global credentials namespace, the following `RoleBinding`
should be created within that `Namespace`:

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: kargo-controller-read-secrets
namespace: kargo-global-creds
subjects:
- kind: ServiceAccount
name: kargo-controller
namespace: kargo
roleRef:
kind: ClusterRole
name: kargo-controller-read-secrets
apiGroup: rbac.authorization.k8s.io
```
:::

:::info
By default, Kargo controllers lack cluster-wide permissions on `Secret`
resources. Instead, the Kargo _management controller_ dynamically expands
controller access to `Secret`s on a namespace-by-namespace basis as new
`Project`s are created.

_It is because this process does not account for "global" credential namespaces
that these bindings must be created manually by an operator._
:::

:::warning
Setting `controller.serviceAccount.clusterWideSecretReadingEnabled` setting to
`true` during Kargo installation will grant Kargo controllers cluster-wide read
permission on `Secret` resources.

__This is highly discouraged, especially in sharded environments where this
permission would have the undesirable effect of granting remote Kargo
controllers read permissions on all `Secret`s throughout the Kargo control
plane's cluster -- including `Secret`s having nothing to do with Kargo.__
:::

:::note
Any matching credentials (exact match _or_ pattern match) found in a project's
own `Namespace` take precedence over those found in any global credentials
Expand All @@ -125,12 +169,6 @@ searched in lexical order by name. Only after no exact match _and_ no pattern
match is found in one global credentials `Namespace` does Kargo search the next.
:::

:::caution
It is important to understand the security implications of this feature. Any
credentials stored in a global credentials `Namespace` will be available to
_all_ Kargo projects.
:::

## Managing Credentials with the CLI

The Kargo CLI can be used to manage credentials in a project's `Namespace.`
Expand Down
Loading