Merge pull request #47 from abiogenesis-now/jyao/add-release-doc-warning

[docs] Add warnings about doc changes between releases

CHANGELOG.md

@@ -1,13 +1,13 @@
 # Changelog
 
-#### v0.3.3 - 2017-08-10
+#### [v0.3.3](https://github.com/heptio/ark/tree/v0.3.3) - 2017-08-10
   * Treat the first field in a schedule's cron expression as minutes, not seconds
 
-#### v0.3.2 - 2017-08-07
+#### [v0.3.2](https://github.com/heptio/ark/tree/v0.3.2) - 2017-08-07
   * Add client-go auth provider plugins for Azure, GCP, OIDC
 
-#### v0.3.1 - 2017-08-03
+#### [v0.3.1](https://github.com/heptio/ark/tree/v0.3.1) - 2017-08-03
   * Fix Makefile VERSION
 
-#### v0.3.0 - 2017-08-03
+#### [v0.3.0](https://github.com/heptio/ark/tree/v0.3.0) - 2017-08-03
   * Initial Release

Makefile

@@ -23,7 +23,7 @@ BIN_DIR = $(OUTPUT_DIR)/bin
 # docker related vars
 DOCKER ?= docker
 REGISTRY ?= gcr.io/heptio-images
-BUILD_IMAGE ?= $(REGISTRY)/golang:1.8-alpine3.6
+BUILD_IMAGE ?= gcr.io/heptio-images/golang:1.8-alpine3.6
 # go build -i installs compiled packages so they can be reused later.
 # This speeds up recompiles.
 BUILDCMD = go build -i -v -ldflags "-X $(GOTARGET)/pkg/buildinfo.Version=$(VERSION) -X $(GOTARGET)/pkg/buildinfo.DockerImage=$(REGISTRY)/$(PROJECT)"

README.md

@@ -45,6 +45,10 @@ Clone or fork the Heptio Ark repo:
 git clone git@github.com:heptio/ark.git
 ```
 
+> NOTE: Documentation may change between releases. See the [Changelog][20] for links to previous versions of this repository and its docs.
+>
+> To ensure that you are working off a specific release, `git checkout <VERSION_TAG>` where `<VERSION_TAG>` is the appropriate tag for the Ark version you wish to use (e.g. "v0.3.3"). You should `git checkout master` only if you're planning on [building the Ark image from scratch][7].
+
 ### 2. Setup
 
 There are two types of Ark instances that work in tandem:

docs/build-from-scratch.md

@@ -21,6 +21,8 @@ The files are installed in `$GOPATH/src/github.com/heptio/ark`.
 
 ## 2. Build
 
+You can build your Ark image locally on the machine where you run your cluster, or you can push it to a private registry. This section covers both workflows.
+
 Set the `$REGISTRY` environment variable (used in the `Makefile`) if you want to push the Heptio Ark images to your own registry. This allows any node in your cluster to pull your locally built image.
 
 `$PROJECT` and `$VERSION` environment variables are also specified in the `Makefile`, and can be similarly modified as desired.
@@ -33,6 +35,9 @@ sudo make all
 To push your image to a registry, use `make push`.
 
 ## 3. Run
+
+### Considerations
+
 When running Heptio Ark, you will need to account for the following (all of which are handled in the [`/examples`][6] manifests):
 * Appropriate RBAC permissions in the cluster
   * *Read access* for all data from the source cluster and namespaces
@@ -44,6 +49,14 @@ When running Heptio Ark, you will need to account for the following (all of whic
 
 See [Cloud Provider Specifics][9] for a more detailed guide.
 
+### Specifying your image
+
+Once your Ark deployment is up and running, **you need to replace the Heptio-provided Ark image with the specific one that you built.** You can do so with the following command:
+```
+kubectl set image deployment/ark ark=$REGISTRY/$PROJECT:$VERSION
+```
+where `$REGISTRY`, `$PROJECT`, and `$VERSION` match what you used in the [build step][3].
+
 [0]: ../README.md
 [1]: #0-prerequisites
 [2]: #1-download

docs/cloud-provider-specifics.md

@@ -1,5 +1,9 @@
 # Cloud Provider Specifics
 
+> NOTE: Documentation may change between releases. See the [Changelog][20] for links to previous versions of this repository and its docs.
+>
+> To ensure that you are working off a specific release, `git checkout <VERSION_TAG>` where `<VERSION_TAG>` is the appropriate tag for the Ark version you wish to use (e.g. "v0.3.3"). You should `git checkout master` only if you're planning on [building the Ark image from scratch][21].
+
 While the [Quickstart][0] uses a local storage service to quickly set up Heptio Ark as a demonstration, this document details additional configurations that are required when integrating with the cloud providers below:
 
 * [Setup][12]
@@ -358,4 +362,6 @@ ark restore create nginx-backup --restore-volumes
 [16]: https://cloud.google.com/compute/docs/gcloud-compute
 [17]: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-application-objects
 [18]: https://docs.microsoft.com/en-us/azure/storage/storage-azure-cli
-[19]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#reclaiming
+[19]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#reclaiming
+[20]: /CHANGELOG.md
+[21]: /docs/build-from-scratch.md