From a4747657371f7dba5d75858424d0a8e485b9b5c3 Mon Sep 17 00:00:00 2001 From: Geri Ochoa Date: Mon, 28 Nov 2022 13:56:06 -0500 Subject: [PATCH] Refactor installation and authentication docs This is the first PR adding vendor-specific documentation. - Refactor installation docs to make it simpler with tabs for generic instructions, Google cloud, and Openshift. This is a multi-PR change. The actual installation doc is created on the Pipelines repo and rendered on the website. - Update the build and push how-to with instructions to authenticate to Google Artifact Registry. - Create a new shortcode to commenting out text in the markdown file. --- .../docs/How-to guides/kaniko-build-push.md | 29 ++++- .../docs/Installation/additional-configs.md | 17 +++ content/en/vendor/google/pipelines-install.md | 88 ++++++++++++++ .../vendor/google/registry-authentication.md | 111 ++++++++++++++++++ content/en/vendor/redhat/pipelines-install.md | 45 +++++++ layouts/shortcodes/comment.html | 1 + 6 files changed, 285 insertions(+), 6 deletions(-) create mode 100644 content/en/docs/Installation/additional-configs.md create mode 100644 content/en/vendor/google/pipelines-install.md create mode 100644 content/en/vendor/google/registry-authentication.md create mode 100644 content/en/vendor/redhat/pipelines-install.md create mode 100644 layouts/shortcodes/comment.html diff --git a/content/en/docs/How-to guides/kaniko-build-push.md b/content/en/docs/How-to guides/kaniko-build-push.md index be38c43..f38a278 100644 --- a/content/en/docs/How-to guides/kaniko-build-push.md +++ b/content/en/docs/How-to guides/kaniko-build-push.md @@ -9,6 +9,10 @@ description: > --- --> +{{% pageinfo %}} +{{% readfile "/vendor/disclaimer.md" %}} +{{% /pageinfo %}} + This guide shows you how to: 1. Create a Task to clone source code from a git repository. @@ -31,7 +35,7 @@ can [skip to the full code samples](#full-code-samples). ``` See the [Pipelines installation documentation][pipelines-inst] for other - installation options. + installation options and vendor specific instructions. 1. Install the [Tekton CLI, `tkn`][tkn-inst], on your machine. @@ -174,11 +178,14 @@ together. In most cases, to push the image to a container registry you must provide authentication credentials first. +{{% tabs %}} + +{{% tab "General Authentication" %}} + 1. Set up authentication with the Docker credential helper and generate the - Docker configuration file, `~/.docker/config.json`, for your registry. This - step is different depending on your registry. + Docker configuration file, `$HOME/.docker/config.json`, for your registry. + This step is different depending on your registry. - - [Google Artifact Registry][google-ar] - [Red Hat Quay][rh-quay] - [Docker Hub][docker-hub] - [Azure container registry][azure] @@ -233,8 +240,6 @@ authentication credentials first. secretName: docker-credentials ``` -See the complete files in the [full code samples section](#full-code-samples). - [secrets]: https://kubernetes.io/docs/concepts/configuration/secret/ [rh-quay]: https://access.redhat.com/documentation/en-us/red_hat_quay/3.4/html-single/use_red_hat_quay/index#allow-robot-access-user-repo [google-ar]: https://cloud.google.com/artifact-registry/docs/docker/authentication @@ -243,6 +248,18 @@ See the complete files in the [full code samples section](#full-code-samples). [az-ecr]: https://aws.amazon.com/blogs/compute/authenticating-amazon-ecr-repositories-for-docker-cli-with-credential-helper/ [jfrog]: https://www.jfrog.com/confluence/display/JFROG/Using+Docker+V1#UsingDockerV1-3.SettingUpAuthentication +{{% /tab %}} + +{{% tab "Google Cloud" %}} + +{{< readfile file="/vendor/google/registry-authentication.md" >}} + +{{% /tab %}} + +{{% /tabs %}} + +See the complete files in the [full code samples section](#full-code-samples). + ## Run your Pipeline You are ready to install the Tasks and run the pipeline. diff --git a/content/en/docs/Installation/additional-configs.md b/content/en/docs/Installation/additional-configs.md new file mode 100644 index 0000000..fa26d07 --- /dev/null +++ b/content/en/docs/Installation/additional-configs.md @@ -0,0 +1,17 @@ + + +{{% readfile "/docs/Pipelines/additional-configs.md" %}} + +--- +{{< card >}} +Source for this document [available on GitHub](https://github.com/tektoncd/pipeline/blob/main/docs/additional-configs.md). +{{< /card >}} + diff --git a/content/en/vendor/google/pipelines-install.md b/content/en/vendor/google/pipelines-install.md new file mode 100644 index 0000000..5a32315 --- /dev/null +++ b/content/en/vendor/google/pipelines-install.md @@ -0,0 +1,88 @@ +Before you proceed, create or select a project on Google Cloud and [install the +gcloud CLI][gcloud-install] on your computer. + +To install Tekton Pipelines: + +1. Enable the Google Kubernetes Engine (GKE) API: + + ```bash + gcloud services enable container.googleapis.com + ``` + +1. Create a cluster with Workload Identity enabled. For example: + + ```bash + gcloud container clusters create tekton-cluster \ + --num-nodes= \ + --region= \ + --workload-pool=.svc.id.goog + ``` + + Where: + + + `` is the cluster location. For example, `us-central1`. + See the documentation about [regional][regional-c] and [zonal][zonal-c] + clusters for more information. + + + `` is the project ID. + + + `` is the number of nodes. + + Workload Identity allows your GKE cluster to access Google Cloud services + using an [Identity Access Management (IAM)][iam-overview] service account. + For example, the [Tekton build and push guide][kaniko-tuto] explains how to + authenticate to Artifact Registry on a cluster with Workload Identity + enabled. + + You can also [enable Workload Idenitity][wi-enable] on an existing cluster. + +1. Follow the regular Kubernetes installation steps. + +**Private clusters** + +If you are running a [private cluster][private-cluster] and experience [problems +with GKE DNS resolution][gke-issue], allow the port `8443` in your firewall +rules. + +```bash +gcloud compute firewall-rules update --allow tcp:8443 +``` + +See the documentation about [firewall rules for private +clusters][private-cluster-fw] for more information. + +**Autopilot** + +If you are using [Autopilot mode][autopilot] on your GKE cluster and +experience [some problems][ap-issue], try the following: + +1. Allow port `8443` in your firewall rules. + + ```bash + gcloud compute firewall-rules update --allow tcp:8443 + ``` + +1. Disable the affinity assistant. + + ```bash + kubectl patch cm feature-flags -n tekton-pipelines \ + -p '{"data":{"disable-affinity-assistant":"true"}}' + ``` + +1. Increase the ephemeral storage. + + +[location]: https://cloud.google.com/artifact-registry/docs/repositories/repo-locations +[gke-issue]: https://github.com/tektoncd/pipeline/issues/3317#issuecomment-708066087 +[gcloud-install]: https://cloud.google.com/sdk/docs/install +[gcloud-project]: https://cloud.google.com/resource-manager/docs/creating-managing-projects +[iam-overview]: https://cloud.google.com/iam/docs/overview +[regional-c]: https://cloud.google.com/kubernetes-engine/docs/concepts/regional-clusters +[zonal-c]: https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-zonal-cluster +[private-cluster]: https://cloud.google.com/kubernetes-engine/docs/concepts/private-cluster-concept +[private-cluster-fw]: https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules +[kaniko-tuto]: /docs/how-to-guides/kaniko-build-push/#container-registry-authentication +[autopilot]: https://cloud.google.com/kubernetes-engine/docs/concepts/autopilot-overview +[ap-issue]: https://github.com/tektoncd/pipeline/issues/3798 +[wi-enable]: https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#enable-existing-cluster + diff --git a/content/en/vendor/google/registry-authentication.md b/content/en/vendor/google/registry-authentication.md new file mode 100644 index 0000000..105162a --- /dev/null +++ b/content/en/vendor/google/registry-authentication.md @@ -0,0 +1,111 @@ +**GKE Workload Identity** + +If you are running your Pipelines on Google Kubernetes Engine (GKE), [create a +cluster with Workload Identity enabled][wi-create] or [enable Workload Identity +on an existing cluster][wi-enable]. This allows you to to run your pipeline and +push images to [Artifact Registry][ar-overview] without authentication +credentials. If you are using Workload Identity, **skip step 2** when you [run +your pipeline](#run-your-pipeline). + +Set up an Artifact Registry repository: + +1. Enable the Artifact Registry API: + + ```bash + gcloud services enable artifactregistry.googleapis.com + ``` + +1. Create a Docker repository to push the image to: + + ```bash + gcloud artifacts repositories create \ + --repository-format=docker \ + --location=us-central1 --description="Docker repository" + ``` + + Replace: + + - `` with the name of your repository. + - `` with the name of your preferred [location][]. For example, + `us-central1`. + +Configure the GKE cluster to allow the Pipeline to push images to Artifact +Registry: + +1. Create a Kubernetes Service Account: + + ```bash + kubectl create serviceaccount + ``` + + Where `` is the name of the service account. For example, `tekton-sa`. + +1. Create a Google Service Account with the same name: + + ```bash + gcloud iam service-accounts create + ``` + +1. Grant the Google Service Account permissions to push to the Artifact + Registry container repository: + + ```bash + gcloud artifacts repositories add-iam-policy-binding \ + --location \ + --member=serviceAccount:build-robot@.iam.gserviceaccount.com \ + --role=roles/artifactregistry.reader \ + --role=roles/artifactregistry.writer + ``` + + Where + + - `` is the name of the [repository][ar-repos]. + - `` is the repository [repository location][location]. + - `` is the [project id][project-id]. + +1. Set up the Workload Identity mappings on the Kubernetes cluster: + + ```bash + kubectl annotate serviceaccount \ + \ + iam.gke.io/gcp-service-account=build-robot@.iam.gserviceaccount.com + ``` + +1. Set up Workload Identity mappings for the Google Service Account: + + ```bash + gcloud iam service-accounts add-iam-policy-binding \ + --role roles/iam.workloadIdentityUser \ + --member "serviceAccount:.svc.id.goog[default/]" \ + build-robot@.iam.gserviceaccount.com + ``` + +This creates two service accounts, an [IAM service account][iam-account] and a +[Kubernetes service account][k8s-account], and "links" them. Workload Identity +allows workloads in your GKE cluster to impersonate IAM service accounts to +access Google Cloud services. + +**Use Docker authentication** + +If you prefer to use Docker authentication to push your image to Artifact +Registry, there are two options: + +- [Use the gcloud credential helper][gcloud-auth]. +- [Use the Standalone Docker credential helper][standalone-auth]. + +In both cases your credentials are saved to a Docker configuration file in your +user home directory: `$HOME/.docker/config.json`. Use this file to follow the +"General Authentication" instructions. + +[workload-identity]: https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity +[wi-create]: https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#enable_on_cluster +[wi-enable]: https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#enable-existing-cluster +[location]: https://cloud.google.com/artifact-registry/docs/repositories/repo-locations +[ar-repos]: https://cloud.google.com/artifact-registry/docs/repositories/create-repos +[project-id]: https://cloud.google.com/resource-manager/docs/creating-managing-projects +[iam-account]: https://cloud.google.com/iam/docs/service-accounts +[k8s-account]: https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/ +[gcloud-auth]: https://cloud.google.com/artifact-registry/docs/docker/authentication#gcloud-helper +[standalone-auth]: https://cloud.google.com/artifact-registry/docs/docker/authentication#standalone-helper +[ar-overview]: https://cloud.google.com/artifact-registry/docs/overview + diff --git a/content/en/vendor/redhat/pipelines-install.md b/content/en/vendor/redhat/pipelines-install.md new file mode 100644 index 0000000..674206f --- /dev/null +++ b/content/en/vendor/redhat/pipelines-install.md @@ -0,0 +1,45 @@ +To install Tekton Pipelines on OpenShift, you must first apply the `anyuid` +security context constraint to the `tekton-pipelines-controller` service +account. This is required to run the webhook Pod. See [Security Context +Constraints][security-con] for more information. + +1. Log on as a user with `cluster-admin` privileges. The following example + uses the default `system:admin` user: + + ```bash + oc login -u system:admin + ``` + +1. Set up the namespace (project) and configure the service account: + + ```bash + oc new-project tekton-pipelines + oc adm policy add-scc-to-user anyuid -z tekton-pipelines-controller + oc adm policy add-scc-to-user anyuid -z tekton-pipelines-webhook + ``` +1. Install Tekton Pipelines: + + ```bash + oc apply --filename https://storage.googleapis.com/tekton-releases/pipeline/latest/release.notags.yaml + ``` + + See the [OpenShift CLI documentation][openshift-cli] for more information on + the `oc` command. + +1. Monitor the installation using the following command until all components + show a `Running` status: + + ```bash + oc get pods --namespace tekton-pipelines --watch + ``` + + **Note:** Hit CTRL + C to stop monitoring. + +Congratulations! You have successfully installed Tekton Pipelines on your +OpenShift environment. + +To run OpenShift 4.x on your laptop (or desktop), take a look at [Red Hat +CodeReady Containers](https://github.com/code-ready/crc). + +[openshift-cli]: https://docs.openshift.com/container-platform/4.3/cli_reference/openshift_cli/getting-started-cli.html +[security-con]: https://docs.openshift.com/container-platform/4.3/authentication/managing-security-context-constraints.html diff --git a/layouts/shortcodes/comment.html b/layouts/shortcodes/comment.html new file mode 100644 index 0000000..d93c127 --- /dev/null +++ b/layouts/shortcodes/comment.html @@ -0,0 +1 @@ +{{ if .Inner }}{{ end }} -- GitLab