add infrastructure permissions docs

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.

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)
+