From 5a54c962031070f5fd05dc1436cd3f6b9415b221 Mon Sep 17 00:00:00 2001 From: Jeffrey Regan Date: Thu, 24 May 2018 10:58:45 -0700 Subject: [PATCH] update readmes --- INSTALL.md | 27 +++++++++++++ README.md | 102 ++++++++++++++++++++++++++++------------------- build/README.md | 57 ++++++++++++++++---------- demos/README.md | 9 ++++- docs/glossary.md | 33 ++++++++------- 5 files changed, 150 insertions(+), 78 deletions(-) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 000000000..6aea87a82 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,27 @@ +[release page]: https://github.com/kubernetes-sigs/kustomize/releases +[Go]: https://golang.org + +## Installation + +Download a binary from the [release page]. + +Or try this to grab the latest official release +using the command line: + +``` +opsys=linux # or darwin, or windows +curl -s https://api.github.com/repos/kubernetes-sigs/kustomize/releases/latest |\ + grep browser_download |\ + grep $opsys |\ + cut -d '"' -f 4 |\ + xargs curl -O -L +mv kustomize_*_${opsys}_amd64 kustomize +chmod u+x kustomize +``` + +To install from head with [Go] v1.10.1 or higher: + + +``` +go get github.com/kubernetes-sigs/kustomize +``` diff --git a/README.md b/README.md index ef8c0c673..da3660033 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ -# kustomize - +[KEP]: https://github.com/kubernetes/community/blob/master/keps/sig-cli/0008-kustomize.md +[`make`]: https://www.gnu.org/software/make +[`sed`]: https://www.gnu.org/software/sed [applied]: docs/glossary.md#apply [base]: docs/glossary.md#base [declarative configuration]: docs/glossary.md#declarative-application-management @@ -7,46 +8,51 @@ [demos]: demos/README.md [imageBase]: docs/base.jpg [imageOverlay]: docs/overlay.jpg +[installation]: INSTALL.md [kubernetes style]: docs/glossary.md#kubernetes-style-object -[KEP]: https://github.com/kubernetes/community/blob/master/keps/sig-cli/0008-kustomize.md [kustomization]: docs/glossary.md#kustomization [overlay]: docs/glossary.md#overlay +[overlays]: docs/glossary.md#overlay +[release page]: https://github.com/kubernetes-sigs/kustomize/releases +[resource]: docs/glossary.md#resource [resources]: docs/glossary.md#resource [sig-cli]: https://github.com/kubernetes/community/blob/master/sig-cli/README.md +[variant]: docs/glossary.md#variant +[variants]: docs/glossary.md#variant [workflows]: docs/workflows.md +# kustomize -`kustomize` is a command line tool supporting -template-free customization of YAML (or JSON) objects -that conform to the [kubernetes style]. If your -objects have a `kind` and a `metadata` field, -`kustomize` can patch them to support configuration -sharing and re-use. +`kustomize` lets you customize raw, template-free YAML +files for multiple purposes, leaving the original YAML +untouched and usable as is. -For more details, try a [demo]. +`kustomize` targets kubernetes; it understands and can +patch [kubernetes style] API objects. It's like +[`make`], in that what it does is declared in a file, +and it's like [`sed`], in that it emits editted text. [![Build Status](https://travis-ci.org/kubernetes-sigs/kustomize.svg?branch=master)](https://travis-ci.org/kubernetes-sigs/kustomize) [![Go Report Card](https://goreportcard.com/badge/github.com/kubernetes-sigs/kustomize)](https://goreportcard.com/report/github.com/kubernetes-sigs/kustomize) +**Installation**: +Download a binary from the [release page], or +see these [installation] alternatives. -## Installation - -This assumes [Go](https://golang.org/) (v1.10.1 or higher) -is installed and your `PATH` contains `$GOPATH/bin`: - - -``` -go get github.com/kubernetes-sigs/kustomize -``` - +Be sure to try one of the tested [demos]. ## Usage -#### 1) Make a customized base -A [base] configuration is a [kustomization] file listing a set of -k8s [resources] - deployments, services, configmaps, -secrets that serve some common purpose. +### Make a [base] + +In some directory containing your YAML [resource] +files (deployments, services, configmaps, etc.), create a +[kustomization] file. + +This file should declare those resources, and any +common customization to apply to them, e.g. _add a +common label_. ![base image][imageBase] @@ -60,15 +66,30 @@ File structure: > └── service.yaml > ``` -Your base could be a fork of someone else's -configuration, that your occasionally rebase from to -capture improvements. +This is your [base]. The resources in it could be a +fork of someone else's configuration. If so, you can +easily rebase from the source material to capture +improvements, because you don't modify the resources +directly. -#### 2) Further customize with overlays +Generate customized YAML with: -An [overlay] customizes your base along different dimensions -for different purposes or different teams, e.g. for -_development_ and _production_. +``` +kustomize build ~/yourApp/base +``` + +The YAML can be directly [applied] to a cluster: + +> ``` +> kustomize build ~/yourApp/base | kubectl apply -f - +> ``` + + +### Create [variants] of a common base using [overlays] + +Manage traditional [variants] of a configuration like +_development_, _staging_ and _production_ using +[overlays]. ![overlay image][imageOverlay] @@ -90,22 +111,23 @@ File structure: > └── replica_count.yaml > ``` -Your overlays could sit in your own repository. +Store your overlays in your own repository. On disk, +the overlay can reference a base in a sibling +directory. This avoids trouble with nesting git +repositories. -#### 3) Run kustomize - -Run `kustomize` on an overlay, e.g. +Generate YAML with ``` kustomize build ~/yourApp/overlays/production ``` -The result is printed to `stdout` as a set of complete -resources, ready to be [applied] to a cluster. See the -[demos]. - +The YAML can be directly [applied] to a cluster: +> ``` +> kustomize build ~/yourApp/overlays/production | kubectl apply -f - +> ``` ## About -This project is sponsored by [sig-cli] ([KEP]). +This tool is sponsored by [sig-cli] ([KEP]). diff --git a/build/README.md b/build/README.md index b38a168a6..e4c9b41e8 100644 --- a/build/README.md +++ b/build/README.md @@ -1,28 +1,45 @@ -## Overview +[releases page]: https://github.com/kubernetes-sigs/kustomize/releases +[`container-builder-local`]: https://github.com/GoogleCloudPlatform/container-builder-local +[Google Container Builder]: https://cloud.google.com/container-builder -This directory contains scripts and configuration files for publishing a -`kustomize` release on [release page](https://github.com/kubernetes-sigs/kustomize/releases) +Scripts and configuration files for publishing a +`kustomize` release on the [releases page]. -## Steps to run build a release locally -Install container-builder-local from [github](https://github.com/GoogleCloudPlatform/container-builder-local). +### Build a release locally -```sh -container-builder-local --config=build/cloudbuild_local.yaml --dryrun=false --write-workspace=/tmp/w . +Install [`container-builder-local`], then run + +``` +container-builder-local \ + --config=build/cloudbuild_local.yaml \ + --dryrun=false --write-workspace=/tmp/w . ``` -You will find the build artifacts under `/tmp/w/dist` directory +to build artifacts under `/tmp/w/dist`. -### Publishing a Release +### Publish a Release -Here are the steps to publish a new release. +Get on an up-to-date master branch: +``` +git checkout master +git fetch upstream +git rebase upstream/master +``` - - Figure out the next version (for ex. v1.0.3) to be released. - - Ensure that you are on master branch and is up-to-date with the remote upstream/master branch. Do the following if you are in doubt: - ``` - git checkout master - git fetch upstream - git rebase upstream/master - ``` - - Tag the repo by running `git tag -a -m " release"` - - Push the tag to `upstream` branch by running `git push upstream ` - - Thats it! The new tag will trigger a job in Google Container Builder and new release should appear in the releases page. +Decide on your version, e.g.: +``` +version=v1.0.3 +``` + +Tag the repo: +``` +git tag -a $version -m "$version release" +``` + +Push the tag upstream: +``` +git push upstream $version +``` + +The new tag will trigger a job in [Google Container +Builder] to put a new release on the [releases page]. diff --git a/demos/README.md b/demos/README.md index a4c9fff67..a44905da5 100644 --- a/demos/README.md +++ b/demos/README.md @@ -1,7 +1,14 @@ # Demos These demos assume that `kustomize` is on your `$PATH`. -They are covered by pre-submit tests. + +They are covered by [pre-commit](../bin/pre-commit.sh) +tests, and should work with HEAD + + +``` +go get github.com/kubernetes-sigs/kustomize +``` * [hello world](helloWorld/README.md) - Deploy multiple (differently configured) variants of a simple Hello diff --git a/docs/glossary.md b/docs/glossary.md index 35445b4f8..3fa5f54c0 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -162,8 +162,8 @@ It's often abbreviated as _k8s_. An object, expressed in a YAML or JSON file, with the [fields required] by kubernetes. Basically just a -`kind` field to identify the type, a `metadata/name` -field to identify the variant, and an `apiVersion` +_kind_ field to identify the type, a _metadata/name_ +field to identify the variant, and an _apiVersion_ field to identify the version (if there's more than one version). @@ -267,7 +267,7 @@ configmap. More generally, a resource can be any correct YAML file that [defines an object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) -with a `kind` and a `metadata/name` field. +with a _kind_ and a _metadata/name_ field. A _resource_ in the content of a REST-ful API is the @@ -290,8 +290,7 @@ The _target_ is the argument to `kustomize build`, e.g.: > ``` `$target` must be a path to a directory that -immediately contains a file called -`kustomization.yaml` (i.e. a [kustomization]). +immediately contains a [kustomization]. The target contains, or refers to, all the information needed to create customized resources to send to the @@ -304,15 +303,15 @@ A target is a [base] or an [overlay]. A _variant_ is the outcome, in a cluster, of applying an [overlay] to a [base]. -> E.g., a _staging_ and _production_ overlay both modify some -> common base to create distinct variants. -> -> The _staging_ variant is the set of resources -> exposed to quality assurance testing, or to some -> external users who'd like to see what the next -> version of production will look like. -> -> The _production_ variant is the set of resources -> exposed to production traffic, and thus may employ -> deployments with a large number of replicas and higher -> cpu and memory requests. +E.g., a _staging_ and _production_ overlay both modify +some common base to create distinct variants. + +The _staging_ variant is the set of resources exposed +to quality assurance testing, or to some external users +who'd like to see what the next version of production +will look like. + +The _production_ variant is the set of resources +exposed to production traffic, and thus may employ +deployments with a large number of replicas and higher +cpu and memory requests.