volumes: document alternates to the gitRepo volume type

content/en/docs/concepts/storage/volumes.md

@@ -370,31 +370,9 @@ spec:
 
 ### gitRepo
 
-A `gitRepo` volume is an example of what can be done as a volume plugin.  It
-mounts an empty directory and clones a git repository into it for your Pod to
-use.  In the future, such volumes may be moved to an even more decoupled model,
-rather than extending the Kubernetes API for every such use case.
-
-Here is an example for gitRepo volume:
-
-```yaml
-apiVersion: v1
-kind: Pod
-metadata:
-  name: server
-spec:
-  containers:
-  - image: nginx
-    name: nginx
-    volumeMounts:
-    - mountPath: /mypath
-      name: git-volume
-  volumes:
-  - name: git-volume
-    gitRepo:
-      repository: "git@somewhere:me/my-git-repository.git"
-      revision: "22f1d8406d464b0c0874075539c1f2e96c253775"
-```
+The `gitRepo` volume type is deprecated. See [_"Configure a Pod with a Git Repo"_](
+/docs/tasks/configure-pod-container/configure-git-repo/) for examples of
+accessing a repo from within a container.
 
 ### glusterfs
 

content/en/docs/tasks/configure-pod-container/configure-git-repo.md

@@ -0,0 +1,62 @@
+---
+title: Configure a Pod with a Git Repo
+content_template: templates/task
+---
+
+{{% capture overview %}}
+
+This page shows how to configure a Pod with a Git repo using an
+[Init Container](/docs/concepts/workloads/pods/init-containers/) to provision a
+volume before the Pod's primary container runs. While these examples are specific
+to Git, the overall strategy can be extended to other version control systems.
+
+{{% /capture %}}
+
+{{% capture prerequisites %}}
+
+* You need to have a Kubernetes cluster, and the kubectl command-line tool must
+be configured to communicate with your cluster. If you do not already have a
+single-node cluster, you can create one by using
+[Minikube](/docs/getting-started-guides/minikube).
+
+* Familiarize yourself with the material in
+[Init Containers](/docs/concepts/workloads/pods/init-containers/).
+
+{{% /capture %}}
+
+{{% capture steps %}}
+
+## Cloning a Git repo
+
+The [emptyDir](/docs/concepts/storage/volumes/#emptydir) volume type can be used
+to share data between multiple containers in a Pod.
+
+First, define a script for cloning a repo to run in the Init Container:
+
+{{< code file="git-repo/configmap.yaml" >}}
+
+Mount this script into the Pod's Init Container and clone to an emptyDir mounted
+into both the Init Container and the Pod's primary container:
+
+{{< code file="git-repo/deployment.yaml" >}}
+
+## Cloning private repos
+
+When cloning private repos, use [Secrets](/docs/concepts/configuration/secret/)
+to pass credentials to the Init Container.
+
+For example, to use a [GitHub personal access token](
+https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
+to clone a private repo, create a secret containing the access token:
+
+    kubectl create secret generic github-access-token --from-file=token=secrets/github-access-token
+
+Modify the Init Container's script to use the access token:
+
+{{< code file="git-repo/private-configmap.yaml" >}}
+
+Finally, expose the access token as an environment variable to the Init Container:
+
+{{< code file="git-repo/private-deployment.yaml" >}}
+
+{{% /capture %}}

content/en/docs/tasks/configure-pod-container/git-repo/configmap.yaml

@@ -0,0 +1,21 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: git-clone
+data:
+  git-clone.sh: |
+    #!/bin/sh -e
+
+    REPO=$1
+    REF=$2
+    DIR=$3
+
+    # Init Containers will re-run on Pod restart. Remove the directory's contents
+    # and reprovision when this happens.
+    if [ -d "$DIR" ]; then
+        rm -rf $( find $DIR -mindepth 1 )
+    fi
+
+    git clone $REPO $DIR
+    cd $DIR
+    git reset --hard $REF

content/en/docs/tasks/configure-pod-container/git-repo/deployment.yaml

@@ -0,0 +1,45 @@
+apiVersion: apps/v1beta1
+kind: Deployment
+metadata:
+  name: nginx-deployment
+  labels:
+    app: nginx
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      initContainers:
+      # Use an Init Container to clone the git repo to an empty directory
+      - name: clone
+        image: alpine/git # Any image with git will do
+        command:
+        - /usr/local/git/git-clone.sh
+        args:
+        - "https://github.com/my/repo.git"
+        - "tags/v1.0.2"
+        - "/mypath"
+        volumeMounts:
+        - name: git-clone
+          mountPath: /usr/local/git
+        - name: git-volume
+          mountPath: /mypath
+      containers:
+      # Pod's container now has access to the cloned repo
+      - image: nginx
+        name: nginx
+        volumeMounts:
+        - mountPath: /mypath
+          name: git-volume
+      volumes:
+      - name: git-volume
+        emptyDir: {}
+      - name: git-clone
+        configMap:
+          name: git-clone
+          defaultMode: 0755

content/en/docs/tasks/configure-pod-container/git-repo/private-configmap.yaml

@@ -0,0 +1,33 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: git-clone-private
+data:
+  git-clone.sh: |
+    #!/bin/sh -e
+
+    REPO=$1
+    REF=$2
+    DIR=$3
+
+    # Init Containers will re-run on Pod restart. Remove the directory's contents
+    # and reprovision when this happens.
+    if [ -d "$DIR" ]; then
+        rm -rf $( find $DIR -mindepth 1 )
+    fi
+
+    if [ -n "$GITHUB_ACCESS_TOKEN" ]; then
+        git config --global credential.https://github.com.username $GITHUB_ACCESS_TOKEN
+
+        # Git Hub access tokens don't use a password but git will still prompt for one
+        export GIT_ASKPASS='true' 
+    fi
+
+    git clone $REPO $DIR
+
+    if [ -n "$GITHUB_ACCESS_TOKEN" ]; then
+        git config --global --unset credential.https://github.com.username
+    fi
+
+    cd $DIR
+    git reset --hard $REF

content/en/docs/tasks/configure-pod-container/git-repo/private-deployment.yaml

@@ -0,0 +1,51 @@
+apiVersion: apps/v1beta1
+kind: Deployment
+metadata:
+  name: nginx-deployment-private
+  labels:
+    app: nginx-private
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: nginx-private
+  template:
+    metadata:
+      labels:
+        app: nginx-private
+    spec:
+      initContainers:
+      # Use an Init Container to clone a private git repo to an empty directory
+      - name: clone
+        image: alpine/git # Any image with git will do
+        env:
+        - name: GITHUB_ACCESS_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: github-access-token
+              key: token
+        command:
+        - /usr/local/git/git-clone.sh
+        args:
+        - "https://github.com/my/private-repo.git"
+        - "tags/v1.0.2"
+        - "/mypath"
+        volumeMounts:
+        - name: git-clone-private
+          mountPath: /usr/local/git
+        - name: git-volume
+          mountPath: /mypath
+      containers:
+      # Pod's container now has access to the cloned repo
+      - image: nginx
+        name: nginx
+        volumeMounts:
+        - mountPath: /mypath
+          name: git-volume
+      volumes:
+      - name: git-volume
+        emptyDir: {}
+      - name: git-clone-private
+        configMap:
+          name: git-clone-private
+          defaultMode: 0755