diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index be0c4bf75b0..99a44303926 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -4,6 +4,7 @@ [Roadmap](./roadmap.md) - [Topics](./topics/topics.md) - [Getting Started](./topics/getting-started.md) + - [Troubleshooting](./topics/troubleshooting.md) - [AAD Integration](./topics/aad-integration.md) - [API Server Endpoint](./topics/api-server-endpoint.md) - [Cloud Provider Config](./topics/cloud-provider-config.md) diff --git a/docs/book/src/developers/development.md b/docs/book/src/developers/development.md index 9948982ab52..2fdcc91b130 100644 --- a/docs/book/src/developers/development.md +++ b/docs/book/src/developers/development.md @@ -21,14 +21,14 @@ - [Tilt for dev in both CAPZ and CAPI](#tilt-for-dev-in-both-capz-and-capi) - [Deploying a workload cluster](#deploying-a-workload-cluster) - [Viewing Telemetry](#viewing-telemetry) - - [Instrumenting Telemetry](#instrumenting-telemetry) - - [Distributed Tracing](#distributed-tracing) - - [Metrics](#metrics) - [Manual Testing](#manual-testing) - [Creating a dev cluster](#creating-a-dev-cluster) - [Building and pushing dev images](#building-and-pushing-dev-images) - [Customizing the cluster deployment](#customizing-the-cluster-deployment) - [Creating the cluster](#creating-the-cluster) + - [Instrumenting Telemetry](#instrumenting-telemetry) + - [Distributed Tracing](#distributed-tracing) + - [Metrics](#metrics) - [Submitting PRs and testing](#submitting-prs-and-testing) - [Executing unit tests](#executing-unit-tests) - [Automated Testing](#automated-testing) @@ -293,7 +293,10 @@ SSH_KEY_FILE=.sshkey rm -f "${SSH_KEY_FILE}" 2>/dev/null ssh-keygen -t rsa -b 2048 -f "${SSH_KEY_FILE}" -N '' 1>/dev/null echo "Machine SSH key generated in ${SSH_KEY_FILE}" +# For Linux the ssh key needs to be b64 encoded because we use the azure api to set it +# Windows doesn't support setting ssh keys so we use cloudbase-init to set which doesn't require base64 export AZURE_SSH_PUBLIC_KEY_B64=$(cat "${SSH_KEY_FILE}.pub" | base64 | tr -d '\r\n') +export AZURE_SSH_PUBLIC_KEY=$(cat "${SSH_KEY_FILE}.pub" | tr -d '\r\n') ``` ⚠️ Please note the generated templates include default values and therefore require the use of `clusterctl` to create the cluster @@ -400,6 +403,7 @@ You can optionally set the following variables: | `SKIP_CREATE_MGMT_CLUSTER` | Skip management cluster creation. If skipping managment cluster creation you must specify `KUBECONFIG` and `SKIP_CLEANUP` | `false` | | `LOCAL_ONLY` | Use Kind local registry and run the subset of tests which don't require a remotely pushed controller image. | `true` | | `REGISTRY` | Registry to push the controller image. | `capzci.azurecr.io/ci-e2e` | +| `CLUSTER_NAME` | Name of an existing workload cluster. Will run specs against existing workload cluster. Use in conjunction with `SKIP_CREATE_MGMT_CLUSTER`, `GINKGO_FOCUS` and `KUBECONFIG`. Must specify only one e2e spec to run against with `GINKGO_FOCUS` such as `export GINKO_FOCUS=Creating.a.VMSS.cluster.with.a.single.control.plane.node`. | | `KUBECONFIG` | Used with `SKIP_CREATE_MGMT_CLUSTER` set to true. Location of kubeconfig for the management cluster you would like to use. Use `kind get kubeconfig --name capz-e2e > kubeconfig.capz-e2e` to get the capz e2e kind cluster config | '~/.kube/config' | You can also customize the configuration of the CAPZ cluster created by the E2E tests (except for `CLUSTER_NAME`, `AZURE_RESOURCE_GROUP`, `AZURE_VNET_NAME`, `CONTROL_PLANE_MACHINE_COUNT`, and `WORKER_MACHINE_COUNT`, since they are generated by individual test cases). See [Customizing the cluster deployment](#customizing-the-cluster-deployment) for more details. diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index 338c35f4595..00000000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,63 +0,0 @@ -# Getting started with cluster-api-provider-azure - -## Prerequisites - -### Requirements - -- A [Microsoft Azure account](https://azure.microsoft.com/en-us/) -- Install the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) - -### Setting up your Azure environment - -An Azure Service Principal is needed for deploying Azure resources. The below instructions utilize [environment-based authentication](https://docs.microsoft.com/en-us/go/azure/azure-sdk-go-authorization#use-environment-based-authentication). - - 1. Login with the Azure CLI. - - ```bash - az login - ``` - - 2. List your Azure subscriptions. - - ```bash - az account list -o table - ``` - - 3. If more than one account is present, select the account that you want to use. - - ```bash - az account set -s - ``` - - 4. Save your Subscription ID in an environment variable. - - ```bash - export AZURE_SUBSCRIPTION_ID="" - ``` - - 5. Create an Azure Service Principal by running the following command or skip this step and use a previously created Azure Service Principal. - NOTE: the "owner" role is required to be able to create role assignments for [system-assigned managed identity](identity.md). - - ```bash - az ad sp create-for-rbac --role contributor - ``` - - 6. Save the output from the above command in environment variables. - - ```bash - export AZURE_TENANT_ID="" - export AZURE_CLIENT_ID="" - export AZURE_CLIENT_SECRET='' - export AZURE_LOCATION="eastus" # this should be an Azure region that your subscription has quota for. - ``` - -:warning: NOTE: If your password contains single quotes (`'`), make sure to escape them. To escape a single quote, close the quoting before it, insert the single quote, and re-open the quoting. -For example, if your password is `foo'blah$`, you should do `export AZURE_CLIENT_SECRET='foo'\''blah$'`. - -### Building your first cluster - -Check out the [Cluster API Quick Start](https://cluster-api.sigs.k8s.io/user/quick-start.html) to create your first Kubernetes cluster on Azure using Cluster API. Make sure to select the "Azure" tabs. - -### Documentation - -Please see the [CAPZ book](https://capz.sigs.k8s.io) for in-depth user documentation.