From 626edc35c88e45403e98b15d644a70a3f128eb68 Mon Sep 17 00:00:00 2001 From: Daniel Foehr Date: Mon, 24 Aug 2020 18:22:03 +0200 Subject: [PATCH] add infrastructure permissions docs --- docs/usage-as-end-user.md | 26 ++++++++++++++---- docs/usage-as-operator.md | 55 ++++++++++++++++++++++++++++++++++++--- 2 files changed, 72 insertions(+), 9 deletions(-) diff --git a/docs/usage-as-end-user.md b/docs/usage-as-end-user.md index 7a508dd81..9d871f3cd 100644 --- a/docs/usage-as-end-user.md +++ b/docs/usage-as-end-user.md @@ -2,11 +2,29 @@ The [`core.gardener.cloud/v1beta1.Shoot` resource](https://github.com/gardener/gardener/blob/master/example/90-shoot.yaml) declares a few fields that are meant to contain provider-specific configuration. -In this document we are describing how this configuration looks like for GCP and provide an example `Shoot` manifest with minimal configuration that you can use to create an GCP cluster (modulo the landscape-specific information like cloud profile names, secret binding names, etc.). +This document describes the configurable options for GCP and provides an example `Shoot` manifest with minimal configuration that can be used to create a GCP cluster (modulo the landscape-specific information like cloud profile names, secret binding names, etc.). -## Provider Secret Data +## GCP Provider Credentials + +In order for Gardener to create a Kubernetes cluster using GCP infrastructure components, a Shoot has to provide credentials with sufficient permissions to the desired GCP project. +Every shoot cluster references a `SecretBinding` which itself references a `Secret`, and this `Secret` contains the provider credentials of the GCP project. +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. +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). +[Create a Service Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts) that shall be used for the Shoot cluster. +[Grant at least the following IAM roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access) to the Service Account. +- Service Account Admin +- Service Account Token Creator +- Service Account User +- Compute Admin + +Create a [JSON Service Account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating_service_account_keys) for the Service Account. +Provide it in the `Secret` (base64 encoded for field `serviceaccount.json`), that is being referenced by the `SecretBinding` in the Shoot cluster configuration. -Every shoot cluster references a `SecretBinding` which itself references a `Secret`, and this `Secret` contains the provider credentials of your GCP project. This `Secret` must look as follows: ```yaml @@ -20,8 +38,6 @@ data: serviceaccount.json: base64(serviceaccount-json) ``` -Please look up https://cloud.google.com/iam/docs/creating-managing-service-accounts as well. - ## `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 7929cff95..170ef055d 100644 --- a/docs/usage-as-operator.md +++ b/docs/usage-as-operator.md @@ -1,10 +1,16 @@ # Using the GCP provider extension with Gardener as operator -The [`core.gardener.cloud/v1alpha1.CloudProfile` resource](https://github.com/gardener/gardener/blob/master/example/30-cloudprofile.yaml) declares a `providerConfig` field that is meant to contain provider-specific configuration. +The [`core.gardener.cloud/v1beta1.CloudProfile` resource](https://github.com/gardener/gardener/blob/master/example/30-cloudprofile.yaml) declares a `providerConfig` field that is meant to contain provider-specific configuration. +The [`core.gardener.cloud/v1beta1.Seed` resource](https://github.com/gardener/gardener/blob/master/example/50-seed.yaml) is structured similarly. +Additionally, it allows configuring settings for the backups of the main etcds' data of shoot clusters control planes running in this seed cluster. -In this document we are describing how this configuration looks like for GCP and provide an example `CloudProfile` manifest with minimal configuration that you can use to allow creating GCP shoot clusters. +This document explains the necessary configuration for this provider extension. -## `CloudProfileConfig` +## `CloudProfile` resource + +This section describes, how the configuration for `CloudProfile`s looks like for GCP by providing an example `CloudProfile` manifest with minimal configuration that can be used to allow the creation of GCP shoot clusters. + +### `CloudProfileConfig` The cloud profile configuration contains information about the real machine image IDs in the GCP environment (image URLs). You have to map every version that you specify in `.spec.machineImages[].versions` here such that the GCP extension knows the image URL for every version you want to offer. @@ -21,7 +27,7 @@ machineImages: image: projects/coreos-cloud/global/images/coreos-stable-2135-6-0-v20190801 ``` -## Example `CloudProfile` manifest +### Example `CloudProfile` manifest If you want to allow that shoots can create VMs with local SSDs volumes then you have to specify the type of the disk with `SCRATCH` in the `.spec.volumeTypes[]` list. Please find below an example `CloudProfile` manifest: @@ -69,3 +75,44 @@ spec: - version: 2135.6.0 image: projects/coreos-cloud/global/images/coreos-stable-2135-6-0-v20190801 ``` + +## `Seed` resource + +This provider extension does not support any provider configuration for the `Seed`'s `.spec.provider.providerConfig` field. +However, it supports to managing of backup infrastructure, i.e., you can specify a configuration for the `.spec.backup` field. + +### Backup configuration + +A Seed of type `gcp` can be configured to perform backups for the main etcds' of the shoot clusters control planes using Google Cloud Storage buckets. + +The location/region where the backups will be stored defaults to the region of the Seed (`spec.provider.region`), but can also be explicitly configured via the field `spec.backup.region`. +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. + +```yaml +--- +apiVersion: core.gardener.cloud/v1beta1 +kind: Seed +metadata: + name: my-seed +spec: + provider: + type: gcp + region: europe-west1 + backup: + provider: gcp + region: europe-west1 # default region + secretRef: + name: backup-credentials + namespace: garden + ... +``` +An example of the referenced secret containing the credentials for the GCP Cloud storage can be found in the [example folder](https://github.com/gardener/gardener-extension-provider-gcp/blob/master/example/30-etcd-backup-secret.yaml). + +#### Permissions for GCP Cloud Storage + +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) +