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.

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.

content/en/docs/Installation/additional-configs.md

+<!--
+---
+title: "Additional Configuration Options"
+linkTitle: "Additional Configuration Options"
+weight: 4
+description: >
+  Additional configurations when installing Tekton Pipelines
+---
+-->
+
+{{% 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 >}}
+

content/en/vendor/google/pipelines-install.md

+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=<nodes> \
+      --region=<location> \
+      --workload-pool=<project-id>.svc.id.goog
+    ```
+
+    Where:
+
+    + `<location>` is the cluster location. For example, `us-central1`.
+      See the documentation about [regional][regional-c] and [zonal][zonal-c]
+      clusters for more information.
+
+    + `<project-id>` is the project ID.
+
+    + `<nodes>` 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 <firewall_rule_name> --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 <firewall_rule_name> --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
+

content/en/vendor/google/registry-authentication.md

+**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-name> \
+      --repository-format=docker \
+      --location=us-central1 --description="Docker repository"
+    ```
+
+    Replace:
+
+    -   `<repository-name>` with the name of your repository.
+    -   `<location>` 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 <sa-name>
+    ```
+
+    Where `<sa-name>` 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 <sa-name>
+    ```
+
+1.  Grant the Google Service Account permissions to push to the Artifact
+    Registry container repository:
+
+    ```bash
+    gcloud artifacts repositories add-iam-policy-binding <ar-repository> \
+      --location <location> \
+      --member=serviceAccount:build-robot@<project_id>.iam.gserviceaccount.com \
+      --role=roles/artifactregistry.reader \
+      --role=roles/artifactregistry.writer
+    ```
+
+    Where
+
+    - `<ar-repository>` is the name of the [repository][ar-repos].
+    - `<location>` is the repository [repository location][location].
+    - `<project_id>` is the [project id][project-id].
+
+1.  Set up the Workload Identity mappings on the Kubernetes cluster:
+
+    ```bash
+    kubectl annotate serviceaccount \
+    <sa-name> \
+    iam.gke.io/gcp-service-account=build-robot@<project_id>.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:<project_id>.svc.id.goog[default/<sa-name>]" \
+      build-robot@<project_id>.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
+

content/en/vendor/redhat/pipelines-install.md

+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

layouts/shortcodes/comment.html

+{{ if .Inner  }}{{ end  }}