Merge pull request #30 from matteo-magni/main

Azure docs

.github/workflows/crossplane-main.yml

@@ -12,7 +12,9 @@ on:
     branches:
       - main
     paths:
-      - '*/crossplane/**'
+      - 'amazon/crossplane/**'
+      - 'azure/crossplane/**'
+      - 'google/crossplane/**'
 
 jobs:
   pre-publish:

docs/assets/extra.css

@@ -0,0 +1,51 @@
+:root > * {
+    --blue: #007bff;
+    --indigo: #6610f2;
+    --purple: #6f42c1;
+    --pink: #e83e8c;
+    --red: #dc3545;
+    --orange: #fd7e14;
+    --yellow: #ffc107;
+    --green: #28a745;
+    --teal: #20c997;
+    --cyan: #17a2b8;
+    --white: #fff;
+    --gray: #6c757d;
+    --gray-dark: #343a40;
+    --primary: #007bff;
+    --secondary: #6c757d;
+    --success: #28a745;
+    --info: #17a2b8;
+    --warning: #ffc107;
+    --danger: #dc3545;
+    --light: #f8f9fa;
+    --dark: #343a40;
+    --breakpoint-xs: 0;
+    --breakpoint-sm: 576px;
+    --breakpoint-md: 768px;
+    --breakpoint-lg: 992px;
+    --breakpoint-xl: 1200px;
+    --font-family-sans-serif: -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans","Liberation Sans",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";
+    --font-family-monospace: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;
+
+    --devcenter-bg: #304250;
+    --ocean: #007AB8;
+    --light-gray: #f7f7f7;
+    --darkmode: #1e2a31;
+    --lightmode: #f4f8fa;
+    --hoveerblue: #0091da;
+    --leaf: #78BE20;
+    --plum: #7F35B2;
+    --aqua: #00C1D5;
+    --lightblue: #F4F8FA;
+    --black: #000;
+
+    --md-primary-fg-color: var(--ocean);
+    --md-accent-fg-color: var(--hoveerblue);
+}
+
+[data-md-color-scheme="slate"] {
+    --md-hue: 200; 
+    --md-primary-fg-color: var(--devcenter-bg);
+    --md-accent-fg-color: var(--leaf);
+}

docs/crossplane/providers/aws.md

@@ -23,7 +23,7 @@ and store the desired release into the `PROVIDER_AWS_RELEASE` variable.
     === "Upbound CLI"
         Do make sure you have installed the `up` CLI as described [here](../index.md) and execute
         ```sh
-        up controlplane provider install xpkg.upbound.io/upbound/provider-aws:${PROVIDER_AWS_RELEASE}
+        up controlplane provider install xpkg.upbound.io/upbound/provider-aws:${PROVIDER_AWS_RELEASE} --name provider-aws
         ```
 
     === "YAML manifest"
@@ -52,9 +52,10 @@ The following paragraphs explain how to configure IRSA for the Crossplane AWS pr
 
 You must create a proper role for the provider to assume, for granting the necessary and sufficient permissions to manage the AWS infrastructure.
 The least-privilege principle applies, therefore it's important to understand the actual needs and create the permission policy accordingly.
-
 For example, the following snippet creates a policy that allows the role it's attached to to execute actions only on the S3 service.
 
+First of all, set your the AWS region you're operating in and your EKS cluster name.
+
 ```sh
 # AWS region you're operating in
 export AWS_REGION="eu-central-1"
@@ -65,10 +66,15 @@ CLUSTER_NAME="my-eks-cluster"
 # define variables for IAM
 ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
 OIDC_ID=$(aws eks describe-cluster --name ${CLUSTER_NAME} --output text --query "cluster.identity.oidc.issuer" | cut -d/ -f3-)
-CROSSPLANE_ROLE=Crossplane-for-${CLUSTER_NAME}
+CROSSPLANE_ROLE="crossplane-for-${CLUSTER_NAME}"
 ROLE_TRUST_POLICY=$(mktemp)
 ROLE_PERMISSION_POLICY=$(mktemp)
+```
 
+You can then define the role's trust policy, in order to allow Crossplane AWS provider's
+service account to assume it as WebIdentity, and then create the role.
+
+```sh
 # prepare the trust policy document
 cat > ${ROLE_TRUST_POLICY} <<EOF
 {
@@ -81,7 +87,7 @@ cat > ${ROLE_TRUST_POLICY} <<EOF
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
             "StringLike": {
-                "${OIDC_ID}:sub": "system:serviceaccount:upbound-system:upbound-provider-aws-*"
+                "${OIDC_ID}:sub": "system:serviceaccount:upbound-system:provider-aws-*"
             }
         }
     }]
@@ -90,7 +96,12 @@ EOF
 
 # create the role with the proper trust policy
 aws iam create-role --role-name ${CROSSPLANE_ROLE} --assume-role-policy-document file://${ROLE_TRUST_POLICY}
+```
 
+Now, the permission policies, that define which permissions are granted to the role, have to be created and attached to the role.
+For this example you will need just one policy, with a number of statements declaring what the role can or cannot do.
+
+```sh
 # create the permission policy document
 cat > ${ROLE_PERMISSION_POLICY} <<EOF
 {
@@ -118,8 +129,7 @@ rm ${ROLE_PERMISSION_POLICY}
 
 ## Create Kubernetes resources
 
-Create a `ProviderConfig` resource to specify IRSA as authentication method
-and the role ARN that must be assumed:
+Create a `ProviderConfig` resource to specify IRSA as authentication method.
 
 ```sh
 kubectl apply -f - <<EOF
@@ -130,11 +140,35 @@ metadata:
 spec:
   credentials:
     source: IRSA
-    webIdentity:
-      roleARN: arn:aws:iam::${ACCOUNT_ID}:role/${CROSSPLANE_ROLE}
 EOF
 ```
 
+Create a `ControllerConfig` resource to specify the AWS provider's settings,
+including the IRSA role to assume:
+
+```sh
+kubectl apply -f - <<EOF
+apiVersion: pkg.crossplane.io/v1alpha1
+kind: ControllerConfig
+metadata:
+  annotations:
+    eks.amazonaws.com/role-arn: arn:aws:iam::${ACCOUNT_ID}:role/${CROSSPLANE_ROLE}
+  name: aws-irsa
+EOF
+```
+
+and patch the AWS provider to use it:
+
+```sh
+kubectl patch providers.pkg.crossplane.io provider-aws --type='merge' --patch '{"spec": { "controllerConfigRef": { "name": "aws-irsa" } } }'
+```
+
+Destroy the existing pods to make sure that new ones will be created:
+
+```sh
+kubectl -n upbound-system delete pods -l pkg.crossplane.io/provider=provider-aws
+```
+
 Now you can test the effectiveness of the configuration by creating a simple S3 bucket:
 
 ```sh
@@ -150,7 +184,7 @@ EOF
 )
 ```
 
-and verifying its status
+and verify its status
 
 ```sh hl_lines="1"
 $ kubectl get buckets.s3.aws.upbound.io ${BUCKET_NAME}
@@ -168,7 +202,7 @@ $ aws s3api list-buckets | jq '.Buckets[]|select(.Name == "'${BUCKET_NAME}'")'
 }
 ```
 
-This proves that the provider is configured correctly, you can now delete the test bucket:
+This proves that the provider is configured correctly and you can safely delete the test bucket:
 
 ```sh
 kubectl delete buckets.s3.aws.upbound.io ${BUCKET_NAME}

docs/crossplane/providers/azure.md

@@ -0,0 +1,156 @@
+---
+title: UXP Azure provider
+description: How to install and configure Upbound's Crossplane Azure provider
+Hero: Install Crossplane UXP Azure provider
+---
+
+Upbound's Azure Provider is an Azure provider for Crossplane that is developed and supported by Upbound.
+
+It can be deployed on top of a Kubernetes cluster with Crossplane using the Upbound CLI
+(see [here](../index.md) for details about installation) or a YAML manifest.
+
+## Installation
+
+You can check available releases on [project's GitHub repository](https://github.com/upbound/provider-azure/releases)
+or using [`gh`](https://cli.github.com/) like
+
+```sh
+gh release list --repo upbound/provider-azure
+```
+
+Store the desired release in the `PROVIDER_AZURE_RELEASE` variable.
+
+!!! Note
+    === "Upbound CLI"
+        Do make sure you have installed the `up` CLI, as described [here](../index.md), and execute
+        ```sh
+        up controlplane provider install xpkg.upbound.io/upbound/provider-azure:${PROVIDER_AZURE_RELEASE}
+        ```
+
+    === "YAML manifest"
+        ```sh
+        kubectl apply -f - <<EOF
+        apiVersion: pkg.crossplane.io/v1
+        kind: Provider
+        metadata:
+          name: provider-azure
+        spec:
+          package: xpkg.upbound.io/upbound/provider-azure:${PROVIDER_AZURE_RELEASE}
+        EOF
+        ```
+
+Ensure the provider is installed and healthy by running the following:
+
+```sh
+kubectl get provider
+```
+
+Which should yield something like the following:
+
+```sh
+NAME             INSTALLED   HEALTHY   PACKAGE                                          AGE
+provider-azure   True        True      xpkg.upbound.io/upbound/provider-azure:v0.17.0   2m35s
+```
+
+Before we can use the provider, we need to supply it with credentials.
+We can use a **Service Provider** or a **Managed Service Identity**.
+
+### Verify Provider
+
+The installation of the Crossplane Azure provider results in the availability of
+new Kubernetes APIs for interacting with Azure resources from within the TAP cluster.
+
+The total number of available resources is relatively high,
+so let us focus on the resources related to CosmosDB.
+
+```sh
+kubectl api-resources --api-group cosmosdb.azure.upbound.io
+```
+
+Running this command prints the following APIs:
+
+```sh
+NAME                   SHORTNAMES   APIVERSION                          NAMESPACED   KIND
+accounts                            cosmosdb.azure.upbound.io/v1beta1   false        Account
+cassandraclusters                   cosmosdb.azure.upbound.io/v1beta1   false        CassandraCluster
+cassandradatacenters                cosmosdb.azure.upbound.io/v1beta1   false        CassandraDatacenter
+cassandrakeyspaces                  cosmosdb.azure.upbound.io/v1beta1   false        CassandraKeySpace
+cassandratables                     cosmosdb.azure.upbound.io/v1beta1   false        CassandraTable
+gremlindatabases                    cosmosdb.azure.upbound.io/v1beta1   false        GremlinDatabase
+gremlingraphs                       cosmosdb.azure.upbound.io/v1beta1   false        GremlinGraph
+mongocollections                    cosmosdb.azure.upbound.io/v1beta1   false        MongoCollection
+mongodatabases                      cosmosdb.azure.upbound.io/v1beta1   false        MongoDatabase
+sqlcontainers                       cosmosdb.azure.upbound.io/v1beta1   false        SQLContainer
+sqldatabases                        cosmosdb.azure.upbound.io/v1beta1   false        SQLDatabase
+sqlfunctions                        cosmosdb.azure.upbound.io/v1beta1   false        SQLFunction
+sqlroleassignments                  cosmosdb.azure.upbound.io/v1beta1   false        SQLRoleAssignment
+sqlroledefinitions                  cosmosdb.azure.upbound.io/v1beta1   false        SQLRoleDefinition
+sqlstoredprocedures                 cosmosdb.azure.upbound.io/v1beta1   false        SQLStoredProcedure
+sqltriggers                         cosmosdb.azure.upbound.io/v1beta1   false        SQLTrigger
+tables                              cosmosdb.azure.upbound.io/v1beta1   false        Table
+```
+
+## Create & Configure Service Provider
+
+Before proceeding, we need an Azure subscription, an Azure account with sufficient privileges, and the `az` (Azure) CLI.
+You can find how to install the CLI [here](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli).
+
+Login to Azure via its CLI (`az`).
+
+```sh
+az login
+```
+
+If you're not sure about your subscription id, you can run the following command:
+
+```sh
+az account show --query "{subscriptionId:id, tenantId:tenantId}"
+```
+
+```sh
+SUBSCRIPTION_ID=
+```
+
+Then create a Service Principle (`sp`), which has sufficient permissions to create all the necessary resources in Azure.
+
+For example:
+
+```sh
+az ad sp create-for-rbac \
+  --sdk-auth \
+  --role Owner \
+  --scopes "/subscriptions/${SUBSCRIPTION_ID}"
+```
+
+!!! warning
+    You probably do not want to give it the role `Owner` if this is a production account.
+
+Save the output as `azure-credentials.json` and create a Kubernetes secret in the `upbound-system` (assuming you use **uxp**).
+
+```sh
+kubectl create secret generic azure-secret \
+  -n upbound-system \
+  --from-file=creds=./azure-credentials.json
+```
+
+We then create a `ProviderConfig`, pointing to this credential.
+
+```sh
+kubectl apply -f - <<EOF
+apiVersion: azure.upbound.io/v1beta1
+kind: ProviderConfig
+metadata:
+  name: default
+spec:
+  credentials:
+    source: Secret
+    secretRef:
+      namespace: upbound-system
+      name: azure-secret
+      key: creds
+EOF
+```
+
+## Create & Configure Managed Service Identity
+
+*TBD*