Skip to content

G
gitlab-ce
Commit 9838acbe authored by Amy Qualls's avatar Amy Qualls
Browse files
Options

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

Docs: Revise Crossplane page for tone and style

See merge request gitlab-org/gitlab!36248
parents 27fe6f83 9fe583ea
Hide whitespace changes
Inline Side-by-side
Showing with 196 additions and 204 deletions
doc/user/clusters/crossplane.md
View file @ 9838acbe
......@@ -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,228 +38,223 @@ 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 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`:
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: crossplane-database-role
labels:
rbac.authorization.k8s.io/aggregate-to-edit: "true"
rules:
- apiGroups:
- database.crossplane.io
resources:
- postgresqlinstances
verbs:
- get
- list
- create
- update
- delete
- patch
- watch
```
1. Apply the cluster role to the cluster:
```shell
kubectl apply -f crossplane-database-role.yaml
```
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:
1. Save the following YAML as `crossplane-database-role.yaml`:
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: crossplane-database-role
labels:
rbac.authorization.k8s.io/aggregate-to-edit: "true"
rules:
- apiGroups:
- database.crossplane.io
resources:
- postgresqlinstances
verbs:
- get
- list
- create
- update
- delete
- patch
- watch
```
1. Apply the cluster role to the cluster:
```shell
kubectl apply -f crossplane-database-role.yaml
```
## Configure Crossplane with a cloud provider
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:
```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.
apiVersion: compute.gcp.crossplane.io/v1alpha3
kind: GlobalAddress
metadata:
name: gitlab-ad-globaladdress
spec:
providerRef:
name: gcp-provider
reclaimPolicy: Delete
name: gitlab-ad-globaladdress
purpose: VPC_PEERING
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.
apiVersion: servicenetworking.gcp.crossplane.io/v1alpha3
kind: Connection
metadata:
name: gitlab-ad-connection
spec:
providerRef:
name: gcp-provider
reclaimPolicy: Delete
parent: services/servicenetworking.googleapis.com
network: projects/$PROJECT_ID/global/networks/$NETWORK_NAME
reservedPeeringRangeRefs:
- name: gitlab-ad-globaladdress
EOF
```
Apply the settings specified in the file with the following command:
```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.
```shell
kubectl describe connection.servicenetworking.gcp.crossplane.io gitlab-ad-connection
kubectl describe globaladdress.compute.gcp.crossplane.io gitlab-ad-globaladdress
```
[configuring private services access](https://cloud.google.com/vpc/docs/configure-private-services-access).
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:
name: gitlab-ad-globaladdress
spec:
providerRef:
name: gcp-provider
reclaimPolicy: Delete
name: gitlab-ad-globaladdress
purpose: VPC_PEERING
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.
apiVersion: servicenetworking.gcp.crossplane.io/v1alpha3
kind: Connection
metadata:
name: gitlab-ad-connection
spec:
providerRef:
name: gcp-provider
reclaimPolicy: Delete
parent: services/servicenetworking.googleapis.com
network: projects/$PROJECT_ID/global/networks/$NETWORK_NAME
reservedPeeringRangeRefs:
- name: gitlab-ad-globaladdress
EOF
```
1. Apply the settings specified in the file with the following command:
```shell
kubectl apply -f network.yaml
```
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
```
## 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
1. A default CloudSQLInstanceClass.
1. A CloudSQLInstanceClass with labels.
```shell
cat > gcp-postgres-standard.yaml <<EOF
apiVersion: database.gcp.crossplane.io/v1beta1
kind: CloudSQLInstanceClass
metadata:
name: cloudsqlinstancepostgresql-standard
labels:
gitlab-ad-demo: "true"
specTemplate:
writeConnectionSecretsToNamespace: gitlab-managed-apps
forProvider:
databaseVersion: POSTGRES_11_7
region: $REGION
settings:
tier: db-custom-1-3840
dataDiskType: PD_SSD
dataDiskSizeGb: 10
ipConfiguration:
privateNetwork: projects/$PROJECT_ID/global/networks/$NETWORK_NAME
# this should match the name of the provider created in the above step
providerRef:
name: gcp-provider
reclaimPolicy: Delete
---
apiVersion: database.gcp.crossplane.io/v1beta1
kind: CloudSQLInstanceClass
metadata:
name: cloudsqlinstancepostgresql-standard-default
annotations:
resourceclass.crossplane.io/is-default-class: "true"
specTemplate:
writeConnectionSecretsToNamespace: gitlab-managed-apps
forProvider:
databaseVersion: POSTGRES_11_7
region: $REGION
settings:
tier: db-custom-1-3840
dataDiskType: PD_SSD
dataDiskSizeGb: 10
ipConfiguration:
privateNetwork: projects/$PROJECT_ID/global/networks/$NETWORK_NAME
# this should match the name of the provider created in the above step
providerRef:
name: gcp-provider
reclaimPolicy: Delete
EOF
```
Apply the resource class configuration with the following command:
```shell
kubectl apply -f gcp-postgres-standard.yaml
```
Verify creation of the Resource class with the following command:
```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.
Use resource classes to define a configuration for the required managed service.
This example defines the PostgreSQL Resource class:
1. Run the following command, which define a `gcp-postgres-standard.yaml` resource
class containing a default `CloudSQLInstanceClass` with labels:
```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:
writeConnectionSecretsToNamespace: gitlab-managed-apps
forProvider:
databaseVersion: POSTGRES_11_7
region: $REGION
settings:
tier: db-custom-1-3840
dataDiskType: PD_SSD
dataDiskSizeGb: 10
ipConfiguration:
privateNetwork: projects/$PROJECT_ID/global/networks/$NETWORK_NAME
# this should match the name of the provider created in the above step
providerRef:
name: gcp-provider
reclaimPolicy: Delete
---
apiVersion: database.gcp.crossplane.io/v1beta1
kind: CloudSQLInstanceClass
metadata:
name: cloudsqlinstancepostgresql-standard-default
annotations:
resourceclass.crossplane.io/is-default-class: "true"
specTemplate:
writeConnectionSecretsToNamespace: gitlab-managed-apps
forProvider:
databaseVersion: POSTGRES_11_7
region: $REGION
settings:
tier: db-custom-1-3840
dataDiskType: PD_SSD
dataDiskSizeGb: 10
ipConfiguration:
privateNetwork: projects/$PROJECT_ID/global/networks/$NETWORK_NAME
# this should match the name of the provider created in the above step
providerRef:
name: gcp-provider
reclaimPolicy: Delete
EOF
```
1. Apply the resource class configuration with the following command:
```shell
kubectl apply -f gcp-postgres-standard.yaml
```
1. Verify creation of the Resource class with the following command:
```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.
## 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
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
`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
value of `postgres.managedClassSelector.matchLabels.gitlab-ad-demo="true"`
will select the CloudSQLInstance class `cloudsqlinstancepostgresql-standard`
to satisfy the claim request.
You can run the Auto DevOps pipeline with either of the following options:
- 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` 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"`
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
```
$ kubectl get postgresqlinstance
Sample Output: The `STATUS` field of the PostgresqlInstance transitions to `BOUND` when it is successfully provisioned.
```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>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7