mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-06-12 01:14:22 +00:00
update readmes
This commit is contained in:
Jeffrey Regan
27
INSTALL.md
Normal file
27
INSTALL.md
Normal file
@@ -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:
|
||||
|
||||
<!-- @installkustomize @test -->
|
||||
```
|
||||
go get github.com/kubernetes-sigs/kustomize
|
||||
```
|
||||
102
README.md
102
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.
|
||||
|
||||
[](https://travis-ci.org/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`:
|
||||
|
||||
<!-- @installkustomize @test -->
|
||||
```
|
||||
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]).
|
||||
|
||||
@@ -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.
|
||||
|
||||
- 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:
|
||||
Get on an up-to-date master branch:
|
||||
```
|
||||
git checkout master
|
||||
git fetch upstream
|
||||
git rebase upstream/master
|
||||
```
|
||||
- Tag the repo by running `git tag -a <version> -m "<version> release"`
|
||||
- Push the tag to `upstream` branch by running `git push upstream <version>`
|
||||
- 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].
|
||||
|
||||
@@ -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
|
||||
|
||||
<!-- @installkustomize @test -->
|
||||
```
|
||||
go get github.com/kubernetes-sigs/kustomize
|
||||
```
|
||||
|
||||
* [hello world](helloWorld/README.md) - Deploy multiple
|
||||
(differently configured) variants of a simple Hello
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user