From e7a812febef51e3703b598b03ead2212d4cef5d2 Mon Sep 17 00:00:00 2001 From: "Kistner, Dominic" Date: Mon, 20 Dec 2021 12:36:49 +0100 Subject: [PATCH] Add docs for managed service account usage --- docs/usage-as-end-user.md | 21 +++++++++++++++++- docs/usage-as-operator.md | 45 +++++++++++++++++++++++++++++++++++++-- 2 files changed, 63 insertions(+), 3 deletions(-) diff --git a/docs/usage-as-end-user.md b/docs/usage-as-end-user.md index 3780f19be..273a1fa36 100644 --- a/docs/usage-as-end-user.md +++ b/docs/usage-as-end-user.md @@ -11,7 +11,7 @@ Every shoot cluster references a `SecretBinding` which itself references a `Secr The `SecretBinding` is configurable in the [Shoot cluster](https://github.com/gardener/gardener/blob/master/example/90-shoot.yaml) with the field `secretBindingName`. The required credentials for the GCP project are a [Service Account Key](https://cloud.google.com/iam/docs/service-accounts#service_account_keys) to authenticate as a [GCP Service Account](https://cloud.google.com/compute/docs/access/service-accounts). -A service account is a special account that can be used by services and applications to interact with Google Cloud Platform APIs. +A service account is a special account that can be used by services and applications to interact with Google Cloud Platform APIs. Applications can use service account credentials to authorize themselves to a set of APIs and perform actions within the permissions granted to the service account. Make sure to [enable the Google Identity and Access Management (IAM) API](https://cloud.google.com/service-usage/docs/enable-disable). @@ -41,6 +41,25 @@ data: ⚠️ Depending on your API usage it can be problematic to reuse the same Service Account Key for different Shoot clusters due to rate limits. Please consider spreading your Shoots over multiple Service Accounts on different GCP projects if you are hitting those limits, see https://cloud.google.com/compute/docs/api-rate-limits. +### Managed Service Accounts + +The operators of the Gardener GCP extension can provide managed service accounts. +This eliminates the need for users to provide an own service account for a Shoot. + +To make use of a managed service account, the GCP secret of a Shoot cluster must contain an `orgID` and a `projectID` field, but no `serviceaccount.json` field. +- The `projectID` field contains the id of the GCP project +- The `orgID` contains the id of the GCP organisation where the GCP project belongs to + +Removing the `serviceaccount.json` field and adding the `projectID` and `orgID` from the secret of an existing Shoot will also let it adopt the managed service account. + +Based on the `orgID` field, the Gardener extension will try to assign the managed service account to the Shoot. +If no managed service account can be assigned then the next operation on the Shoot will fail. + +⚠️ The managed service account need to be assigned to the users GCP project with [proper permissions](#gcp-provider-credentials) before using it. + +In addition to use this feature the user project need to have the organisation policy enabled that allow the assignment of service accounts originated in a different project of the same organisation. +More information are available [here](https://cloud.google.com/iam/docs/impersonating-service-accounts#binding-to-resources). + ## `InfrastructureConfig` The infrastructure configuration mainly describes how the network layout looks like in order to create the shoot worker nodes in a later step, thus, prepares everything relevant to create VMs, load balancers, volumes, etc. diff --git a/docs/usage-as-operator.md b/docs/usage-as-operator.md index 170ef055d..e4854cd58 100644 --- a/docs/usage-as-operator.md +++ b/docs/usage-as-operator.md @@ -89,7 +89,7 @@ The location/region where the backups will be stored defaults to the region of t The region of the backup can be different from where the seed cluster is running. However, usually it makes sense to pick the same region for the backup bucket as used for the Seed cluster. -Please find below an example `Seed` manifest (partly) that configures backups using Google Cloud Storage buckets. +Please find below an example `Seed` manifest (partly) that configures backups using Google Cloud Storage buckets. ```yaml --- @@ -113,6 +113,47 @@ An example of the referenced secret containing the credentials for the GCP Cloud #### Permissions for GCP Cloud Storage -Please make sure the service account associated with the provided credentials has the following IAM roles. +Please make sure the service account associated with the provided credentials has the following IAM roles. - [Storage Admin](https://cloud.google.com/storage/docs/access-control/iam-roles) +## Miscellaneous + +### Gardener managed Service Accounts + +The operators of the Gardener GCP extension can provide a list of managed service accounts (technical users) that can be used for GCP Shoots. +This eliminates the need for users to provide own service account for their clusters. + +GCP service accounts are always bound to one project. +But there is an option to assign a service account originated in a different project of the same GCP organisation to a project. +Based on this approach Gardener operators can provide a project which contains managed service accounts and users could assign service accounts from this project with proper permissions to their projects. + +To use this feature the user project need to have the organisation policy enabled that allow the assignment of service accounts originated in a different project of the same organisation. +More information are available [here](https://cloud.google.com/iam/docs/impersonating-service-accounts#binding-to-resources). + +In case the user provide an own service account in the Shoot secret, this one will be used instead of the managed one provided by the operator. + +Each managed service account will be maintained in a `Secret` like that: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: service-account-my-org + namespace: extension-provider-gcp + labels: + gcp.provider.extensions.gardener.cloud/purpose: service-account-secret +data: + orgID: base64(my-gcp-org-id) + serviceaccount.json: base64(my-service-account-json-without-project-id-field) +type: Opaque +``` + +The user needs to provide in its Shoot secret a `orgID` and `projectID`. + +The managed service account will be assigned based on the `orgID`. +In case there is a managed service account secret with a matching `orgID`, this one will be used for the Shoot. +If there is no matching managed service account secret then the next Shoot operation will fail. + +One of the benefits of having managed service account is that the operator controls the lifecycle of the service account and can rotate its secrets. + +After the service account secret has been rotated and the corresponding secret is updated, all Shoot clusters using it need to be reconciled or the last operation to be retried.