kubernetes
/
kubectl
mirror of https://github.com/kubernetes/kubectl.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

kinflate: improved README and added getting-started

This commit is contained in:
Sunil Arora 2018-02-13 14:37:18 -08:00
parent 3483128153
commit ec745a86f4
2 changed files with 308 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
cmd/kinflate/README.md
View File

@ -1,38 +1,77 @@
# kinflate # Overview
`kinflate` is a kubernetes cluster configuration `kinflate` is a command line interface to manage Kubernetes Application configuration.
utility.
It reads a cluster app definition from a
directory of YAML files, and creates new YAML suitable
for directly piping to `kubectl apply`.
## Declarative Application Management
kinflate is a a prototype of ideas discussed in the
[Declarative Application
Management (DAM) proposal](https://goo.gl/T66ZcD).
DAM encourages one to use literal kubernetes resource
declarations to configure a cluster. DAM understands
new declarations to modify resources, rather than
achieving modification via templates or configuration
languages.
DAM facilitates coupling cluster state changes to version
control commits. It encourages forking a configuration,
customizing it, and occasionally rebasing to capture
upgrades from the original configuration.
## Installation ## Installation
`kinflate` is written in Go and can be installed using `go get`:
<!-- @installKinflate @test --> <!-- @installKinflate @test -->
```shell
go get -u k8s.io/kubectl/cmd/kinflate
``` ```
go get k8s.io/kubectl/cmd/kinflate
After running the above command, `kinflate` should get installed in your `GOPATH/bin` directory.
## Usage
This section explains sub-commands of `kinflate` using examples.
### init
`kinflate init` initializes a directory by creating an application manifest file named `Kube-manifest.yaml`. This command should be run in the same directory where application config resides.
```shell
kinflate init
``` ```
### set nameprefix
`kinflate set nameprefix` updates the nameprefix field in the [manifest].
`kinflate inflate` uses the prefix to generate prefixed names for Kubernetes resources.
Examples
```shell
# set nameprefix to 'staging'
kinflate set nameprefix staging
# set nameprefix to 'john`
kinflate set nameprefix john
```
### add
`kinflate add` adds a resource, configmap or secret to the [manifest].
#### examples
```shell
# adds a resource to the manifest
kinflate add resource <path/to/resource-file-or-dir>
# adds a configmap from a literal or file-source to the manifest
kinflate add configmap my-configmap --from-file=my-key=file/path --from-literal=my-literal=12345
# Adds a generic secret to the Manifest (with a specified key)
kinflate add secret generic my-secret --from-file=my-key=file/path --from-literal=my-literal=12345
# Adds a TLS secret to the Manifest (with a specified key)
kinflate add secret tls my-tls-secret --cert=cert/path.cert --key=key/path.key
```
### inflate
`kinflate inflate` generates application configuration by applying
transformations (e.g. name-prefix, label, annotations) specified in the [manifest].
#### examples
```shell
# generate application configuration and output to stdout
kinflate inflate -f <path/to/application/dir>
# generate application configuration and apply it to a Kubernetes cluster
kinflate inflate -f <path/to/application/dir> | kubectl apply -f -
```
## Demos and tutorial ## Demos and tutorial
* [Getting Started](getting_started.md)
* [Short demo](shortDemo.md) * [Short demo](shortDemo.md)
* [Longer demo / tutorial](longerDemo/README.md) * [Longer demo / tutorial](longerDemo/README.md)

243
cmd/kinflate/getting_started.md Normal file
View File

@ -0,0 +1,243 @@
# Kinflate: Getting Started
In this `getting started` guide, we will take an off-the-shelf MySQL configuration for Kubernetes and customize it to suit our production scenario.
In production environment, we want:
- MySQL resource names to be prefixed by 'prod-' to make them distinguishable.
- MySQL resources to have 'env: prod' labels so that we can use label selector to query these.
- MySQL to use persistent disk for storing data.
## Installation
If you have `kinflate` installed already, then you can skip this step. `kinflate` can be installed using `go get`:
<!-- @installKinflate @test -->
```shell
go get k8s.io/kubectl/cmd/kinflate
```
This fetches kinflate and install `kinflate` executable under `GOPATH/bin` - you will want that on your $PATH.
### Get off-the-shelf MySQL configs for Kubernetes
Download a sample MySQL YAML manifest files:
<!-- @makeMySQLDir @test -->
```shell
MYSQL_DIR=$HOME/kinflate_demo/mysql
rm -rf $MYSQL_DIR && mkdir -p $MYSQL_DIR
cd $MYSQL_DIR
# Get MySQL configs
for f in service secret deployment ; do \
wget https://raw.githubusercontent.com/kinflate/mysql/master/emptyDir/$f.yaml ; \
done
```
This downloads YAML files `deployment.yaml`, `service.yaml` and `secret.yaml` which are needed to run MySQL in a Kubernetes cluster.
### Initialization
Now that we have base configuration for MySQL in place, we can begin with customization for production environment. Follow the step below:
<!-- @initApp @test -->
```shell
mkdir -p $MYSQL_DIR/prod
cd $MYSQL_DIR/prod
#initialize the customization
kinflate init
cat Kube-manifest.yaml
```
`Kube-manifest.yaml` should contain:
```
apiVersion: manifest.k8s.io/v1alpha1
kind: Manifest
metadata:
name: helloworld
description: helloworld does useful stuff.
namePrefix: some-prefix
# Labels to add to all objects and selectors.
# These labels would also be used to form the selector for apply --prune
# Named differently than “labels” to avoid confusion with metadata for this object
objectLabels:
app: helloworld
objectAnnotations:
note: This is a example annotation
resources:
- deployment.yaml
- service.yaml
# There could also be configmaps in Base, which would make these overlays
configmaps: []
# There could be secrets in Base, if just using a fork/rebase workflow
secrets: []
recursive: true
```
Lets break this down:
- First step create a directory called `prod` and switches to that dir. We will keep all the resources related to production customization in this directory.
- `kinflate init` generates a kinflate manifest file called `Kube-manifest.yaml` that contains metadata about the customizations. You can think of this file as containing instructions which inflate will use to apply to generate the required configuration.
### Add resources
Lets add resource files that we want to `kinflate` to act on. Steps below add the three resources for MySQL.
<!-- @addResources @test -->
```shell
cd $MYSQL_DIR/prod
# add the MySQL resources
kinflate add resource ../secret.yaml
kinflate add resource ../service.yaml
kinflate add resource ../deployment.yaml
cat Kube-manifest.yaml
```
`Kube-manifest.yaml`'s resources section should contain:
```
apiVersion: manifest.k8s.io/v1alpha1
....
....
resources:
- ../secret.yaml
- ../service.yaml
- ../deployment.yaml
```
Now we are ready to apply our first customization.
### NamePrefix Customization
We want MySQL resources to begin with prefix 'prod' in production environment. Follow the steps below:
<!-- @customizeLabel @test -->
```shell
cd $MYSQL_DIR/prod
kinflate set nameprefix 'prod-'
cat Kube-manifest.yaml
```
`Kube-manifest.yaml` should have updated value of namePrefix field:
```
apiVersion: manifest.k8s.io/v1alpha1
.....
.....
namePrefix: prod-
objectAnnotations:
note: This is a example annotation
.....
```
Lets break this down:
- `kinflate set nameprex <prefix>` updates the `namePrefix` directive to `prod` in the manifest file.
- Now if you view the `Kube-manifest.yaml`, you will see `namePrefix` directive updated. Editing the `namePrefix` directive in the file will also achieve the same thing.
At this point you can run `kinflate inflate` to generate name-prefixed configuration as shown below.
<!-- @genNamePrefixConfig @test -->
```shell
cd $MYSQL_DIR/prod
# lets generate name-prefixed resources
kinflate inflate -f .
```
Output should contain:
```
apiVersion: v1
data:
password: YWRtaW4=
kind: Secret
metadata:
....
....
name: prod-mysql-pass-d2gtcm2t2k
---
apiVersion: v1
kind: Service
metadata:
....
....
name: prod-mysql
spec:
....
---
apiVersion: apps/v1beta2
kind: Deployment
metadata:
....
....
name: prod-mysql
spec:
selector:
....
....
```
### Label Customization
We want resources in production environment to have certain labels so that we can query them by label selector. `kinflate` does not have `set label` command to add label, but we can edit `Kube-manifest.yaml` file under `prod` directory and add the production labels under `objectLabels` fields as highlighted below.
```
cd $MYSQL_DIR/prod
edit Kube-manifest.yaml
# Edit the objectLabels
....
objectLabels:
app: prod
....
```
At this point, running `kinflate inflate -f .` will generate MySQL configs with name-prefix 'prod-' and labels `env:prod`.
### Storage customization
Off the shelf MySQL uses `emptyDir` type volume, which gets wiped away if the MySQL Pod is recreated, and that is certainly not desirable for production environment. So
we want to use Persistent Disk in production. Kinflate lets you apply `patches` to the resources.
<!-- @customizeOverlay @test -->
```shell
cd $MYSQL_DIR/prod
# create a patch for persistent-disk.yaml
cat <<'EOF' > persistent-disk.yaml
apiVersion: apps/v1beta2 # for versions before 1.9.0 use apps/v1beta2
kind: Deployment
metadata:
name: mysql
spec:
template:
spec:
volumes:
- name: mysql-persistent-storage
emptyDir: null
gcePersistentDisk:
pdName: mysql-persistent-storage
EOF
# edit the manifest file to add the above patch or run following command
cat <<'EOF' >> $MYSQL_DIR/prod/Kube-manifest.yaml
patches:
- persistent-disk.yaml
EOF
```
Lets break this down:
- In the first step, we created a YAML file named `persistent-disk.yaml` to patch the resource defined in deployment.yaml
- Then we added `persistent-disk.yaml` to list of `patches` in `Kube-manifest.yaml`. `kinflate inflate` will apply this patch to the deployment resource with the name `mysql` as defined in the patch.
At this point, if you run `kinflate inflate -f .`, it will generate the Kubernetes config for production environement.