Merge branch 'docs-aqualls-crossplane' into 'master'

Docs: Revise Crossplane page for tone and style

See merge request gitlab-org/gitlab!36248

doc/user/clusters/crossplane.md

@@ -6,17 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Crossplane configuration
 
-Once Crossplane [is installed](applications.md#crossplane), it must be configured for
-use.
-
+After [installing](applications.md#crossplane) Crossplane, you must configure it for use.
 The process of configuring Crossplane includes:
 
-1. Configuring RBAC permissions.
-1. Configuring Crossplane with a cloud provider.
-1. Configure managed service access.
-1. Setting up Resource classes.
-1. Using Auto DevOps configuration options.
-1. Connect to the PostgreSQL instance.
+1. [Configure RBAC permissions](#configure-rbac-permissions).
+1. [Configure Crossplane with a cloud provider](#configure-crossplane-with-a-cloud-provider).
+1. [Configure managed service access](#configure-managed-service-access).
+1. [Set up Resource classes](#setting-up-resource-classes).
+1. Use [Auto DevOps configuration options](#auto-devops-configuration-options).
+1. [Connect to the PostgreSQL instance](#connect-to-the-postgresql-instance).
 
 To allow Crossplane to provision cloud services such as PostgreSQL, the cloud provider
 stack must be configured with a user account. For example:
@@ -24,14 +22,13 @@ stack must be configured with a user account. For example:
 - A service account for GCP.
 - An IAM user for AWS.
 
-Important notes:
+Some important notes:
 
-- This guide uses GCP as an example. However, the process for AWS and Azure will be
-similar.
-- Crossplane requires the Kubernetes cluster to be VPC native with Alias IPs enabled so
-that the IP address of the pods are routable within the GCP network.
+- This guide uses GCP as an example, but the processes for AWS and Azure are similar.
+- Crossplane requires the Kubernetes cluster to be VPC native with Alias IPs enabled,
+  so the IP addresses of the pods can be routed within the GCP network.
 
-First, we need to declare some environment variables with configuration that will be used throughout this guide:
+First, declare some environment variables with configuration for use in this guide:
 
 ```shell
 export PROJECT_ID=crossplane-playground # the GCP project where all resources reside.
@@ -41,11 +38,12 @@ export REGION=us-central1 # the GCP region where the GKE cluster is provisioned.
 
 ## Configure RBAC permissions
 
-- For GitLab-managed clusters, RBAC is configured automatically.
+For GitLab-managed clusters, role-based access control (RBAC) is configured automatically.
 
-- For non-GitLab managed clusters, ensure that the service account for the token provided can manage resources in the `database.crossplane.io` API group:
+For non-GitLab managed clusters, ensure that the service account for the token
+provided can manage resources in the `database.crossplane.io` API group:
 
-  1. Save the following YAML as `crossplane-database-role.yaml`:
+1. Save the following YAML as `crossplane-database-role.yaml`:
 
    ```yaml
    apiVersion: rbac.authorization.k8s.io/v1
@@ -69,7 +67,7 @@ export REGION=us-central1 # the GCP region where the GKE cluster is provisioned.
          - watch
    ```
 
-  1. Apply the cluster role to the cluster:
+1. Apply the cluster role to the cluster:
 
    ```shell
    kubectl apply -f crossplane-database-role.yaml
@@ -80,32 +78,34 @@ export REGION=us-central1 # the GCP region where the GKE cluster is provisioned.
 See [Configure Your Cloud Provider Account](https://crossplane.github.io/docs/v0.4/cloud-providers.html)
 to configure the installed cloud provider stack with a user account.
 
-Note that the Secret and the Provider resource referencing the Secret needs to be
+NOTE: **Note:**
+The Secret, and the Provider resource referencing the Secret, must be
 applied to the `gitlab-managed-apps` namespace in the guide. Make sure you change that
 while following the process.
 
-[Configure Providers](https://crossplane.github.io/docs/v0.4/cloud-providers.html)
-
 ## Configure Managed Service Access
 
-We need to configure connectivity between the PostgreSQL database and the GKE cluster.
-This can done by either:
+Next, configure connectivity between the PostgreSQL database and the GKE cluster
+by either:
 
 - Using Crossplane as demonstrated below.
 - Directly in the GCP console by
-[configuring private services access](https://cloud.google.com/vpc/docs/configure-private-services-access).
-Create a GlobalAddress and Connection resources:
+  [configuring private services access](https://cloud.google.com/vpc/docs/configure-private-services-access).
 
-```shell
-cat > network.yaml <<EOF
----
-# gitlab-ad-globaladdress defines the IP range that will be allocated for cloud services connecting to the instances in the given Network.
+1. Run the following command, which creates a `network.yaml` file, and configures
+   `GlobalAddress` and connection resources:
+
+   ```plaintext
+   cat > network.yaml <<EOF
+   ---
+   # gitlab-ad-globaladdress defines the IP range that will be allocated
+   # for cloud services connecting to the instances in the given Network.
 
-apiVersion: compute.gcp.crossplane.io/v1alpha3
-kind: GlobalAddress
-metadata:
+   apiVersion: compute.gcp.crossplane.io/v1alpha3
+   kind: GlobalAddress
+   metadata:
      name: gitlab-ad-globaladdress
-spec:
+   spec:
      providerRef:
        name: gcp-provider
      reclaimPolicy: Delete
@@ -114,15 +114,16 @@ spec:
      addressType: INTERNAL
      prefixLength: 16
      network: projects/$PROJECT_ID/global/networks/$NETWORK_NAME
----
-# gitlab-ad-connection is what allows cloud services to use the allocated GlobalAddress for communication. Behind
-# the scenes, it creates a VPC peering to the network that those service instances actually live.
+   ---
+   # gitlab-ad-connection is what allows cloud services to use the allocated
+   # GlobalAddress for communication. Behind the scenes, it creates a VPC peering
+   # to the network that those service instances actually live.
 
-apiVersion: servicenetworking.gcp.crossplane.io/v1alpha3
-kind: Connection
-metadata:
+   apiVersion: servicenetworking.gcp.crossplane.io/v1alpha3
+   kind: Connection
+   metadata:
      name: gitlab-ad-connection
-spec:
+   spec:
      providerRef:
        name: gcp-provider
      reclaimPolicy: Delete
@@ -130,41 +131,39 @@ spec:
      network: projects/$PROJECT_ID/global/networks/$NETWORK_NAME
      reservedPeeringRangeRefs:
        - name: gitlab-ad-globaladdress
-EOF
-```
+   EOF
+   ```
 
-Apply the settings specified in the file with the following command:
+1. Apply the settings specified in the file with the following command:
 
-```shell
-kubectl apply -f network.yaml
-```
+   ```shell
+   kubectl apply -f network.yaml
+   ```
 
-You can verify creation of the network resources with the following commands.
-Verify that the status of both of these resources is ready and is synced.
+1. Verify the creation of the network resources, and that both resources are ready and synced.
 
-```shell
-kubectl describe connection.servicenetworking.gcp.crossplane.io gitlab-ad-connection
-kubectl describe globaladdress.compute.gcp.crossplane.io gitlab-ad-globaladdress
-```
+   ```shell
+   kubectl describe connection.servicenetworking.gcp.crossplane.io gitlab-ad-connection
+   kubectl describe globaladdress.compute.gcp.crossplane.io gitlab-ad-globaladdress
+   ```
 
 ## Setting up Resource classes
 
-Resource classes are a way of defining a configuration for the required managed service. We will define the PostgreSQL Resource class
-
-- Define a `gcp-postgres-standard.yaml` resource class which contains
+Use resource classes to define a configuration for the required managed service.
+This example defines the PostgreSQL Resource class:
 
-1. A default CloudSQLInstanceClass.
-1. A CloudSQLInstanceClass with labels.
+1. Run the following command, which define a `gcp-postgres-standard.yaml` resource
+   class containing a default `CloudSQLInstanceClass` with labels:
 
-```shell
-cat > gcp-postgres-standard.yaml <<EOF
-apiVersion: database.gcp.crossplane.io/v1beta1
-kind: CloudSQLInstanceClass
-metadata:
+   ```plaintext
+   cat > gcp-postgres-standard.yaml <<EOF
+   apiVersion: database.gcp.crossplane.io/v1beta1
+   kind: CloudSQLInstanceClass
+   metadata:
      name: cloudsqlinstancepostgresql-standard
      labels:
        gitlab-ad-demo: "true"
-specTemplate:
+   specTemplate:
      writeConnectionSecretsToNamespace: gitlab-managed-apps
      forProvider:
        databaseVersion: POSTGRES_11_7
@@ -179,14 +178,14 @@ specTemplate:
      providerRef:
        name: gcp-provider
      reclaimPolicy: Delete
----
-apiVersion: database.gcp.crossplane.io/v1beta1
-kind: CloudSQLInstanceClass
-metadata:
+   ---
+   apiVersion: database.gcp.crossplane.io/v1beta1
+   kind: CloudSQLInstanceClass
+   metadata:
      name: cloudsqlinstancepostgresql-standard-default
      annotations:
        resourceclass.crossplane.io/is-default-class: "true"
-specTemplate:
+   specTemplate:
      writeConnectionSecretsToNamespace: gitlab-managed-apps
      forProvider:
        databaseVersion: POSTGRES_11_7
@@ -201,68 +200,61 @@ specTemplate:
      providerRef:
        name: gcp-provider
      reclaimPolicy: Delete
-EOF
-```
+   EOF
+   ```
 
-Apply the resource class configuration with the following command:
+1. Apply the resource class configuration with the following command:
 
-```shell
-kubectl apply -f gcp-postgres-standard.yaml
-```
+   ```shell
+   kubectl apply -f gcp-postgres-standard.yaml
+   ```
 
-Verify creation of the Resource class with the following command:
+1. Verify creation of the Resource class with the following command:
 
-```shell
-kubectl get cloudsqlinstanceclasses
-```
+   ```shell
+   kubectl get cloudsqlinstanceclasses
+   ```
 
-The Resource Classes allow you to define classes of service for a managed service. We could create another `CloudSQLInstanceClass` which requests for a larger or a faster disk. It could also request for a specific version of the database.
+The Resource Classes allow you to define classes of service for a managed service.
+We could create another `CloudSQLInstanceClass` which requests for a larger or a
+faster disk. It could also request for a specific version of the database.
 
 ## Auto DevOps Configuration Options
 
-The Auto DevOps pipeline can be run with the following options:
-
-The Environment variables, `AUTO_DEVOPS_POSTGRES_MANAGED` and `AUTO_DEVOPS_POSTGRES_MANAGED_CLASS_SELECTOR` need to be set to provision PostgreSQL using Crossplane
+You can run the Auto DevOps pipeline with either of the following options:
 
-Alternatively, the following options can be overridden from the values for the Helm chart.
-
-- `postgres.managed` set to true which will select a default resource class.
-     The resource class needs to be marked with the annotation
+- Setting the Environment variables `AUTO_DEVOPS_POSTGRES_MANAGED` and
+  `AUTO_DEVOPS_POSTGRES_MANAGED_CLASS_SELECTOR` to provision PostgreSQL using Crossplane.
+- Overriding values for the Helm chart:
+  - Set `postgres.managed` to `true`, which selects a default resource class.
+    Mark the resource class with the annotation
     `resourceclass.crossplane.io/is-default-class: "true"`. The CloudSQLInstanceClass
-     `cloudsqlinstancepostgresql-standard-default` will be used to satisfy the claim.
-
-- `postgres.managed` set to `true` with `postgres.managedClassSelector`
-     providing the resource class to choose based on labels. In this case, the
+    `cloudsqlinstancepostgresql-standard-default` is used to satisfy the claim.
+  - Set `postgres.managed` to `true` with `postgres.managedClassSelector`
+    providing the resource class to choose, based on labels. In this case, the
     value of `postgres.managedClassSelector.matchLabels.gitlab-ad-demo="true"`
-     will select the CloudSQLInstance class `cloudsqlinstancepostgresql-standard`
+    selects the CloudSQLInstance class `cloudsqlinstancepostgresql-standard`
     to satisfy the claim request.
 
 The Auto DevOps pipeline should provision a PostgresqlInstance when it runs successfully.
 
-Verify creation of the PostgreSQL Instance.
+To verify the PostgreSQL instance was created, run this command. When the `STATUS`
+field of the PostgresqlInstance changes to `BOUND`, it's successfully provisioned:
 
 ```shell
-kubectl get postgresqlinstance
-```
-
-Sample Output: The `STATUS` field of the PostgresqlInstance transitions to `BOUND` when it is successfully provisioned.
+$ kubectl get postgresqlinstance
 
-```plaintext
 NAME            STATUS   CLASS-KIND              CLASS-NAME                            RESOURCE-KIND      RESOURCE-NAME                               AGE
 staging-test8   Bound    CloudSQLInstanceClass   cloudsqlinstancepostgresql-standard   CloudSQLInstance   xp-ad-demo-24-staging-staging-test8-jj55c   9m
 ```
 
-The endpoint of the PostgreSQL instance, and the user credentials, are present in a secret called `app-postgres` within the same project namespace.
-
-Verify the secret with the database information is created with the following command:
+The endpoint of the PostgreSQL instance, and the user credentials, are present in
+a secret called `app-postgres` within the same project namespace. You can verify the
+secret with the following command:
 
 ```shell
-kubectl describe secret app-postgres
-```
-
-Sample Output:
+$ kubectl describe secret app-postgres
 
-```plaintext
 Name:         app-postgres
 Namespace:    xp-ad-demo-24-staging
 Labels:       <none>