Skip to content
This repository has been archived by the owner on Feb 15, 2022. It is now read-only.

Commit

Permalink
[docs]: formatted to 80char line length (#224)
Browse files Browse the repository at this point in the history
  • Loading branch information
evanlouie authored Jul 12, 2019
1 parent ffc0c63 commit 2ab2775
Show file tree
Hide file tree
Showing 7 changed files with 332 additions and 108 deletions.
3 changes: 3 additions & 0 deletions .prettierrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"proseWrap": "always"
}
158 changes: 126 additions & 32 deletions README.md

Large diffs are not rendered by default.

3 changes: 2 additions & 1 deletion docs/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,4 +63,5 @@ run `fab install` and look at the warning logs to see which components are
asking for which variables and tokens (missing env vars will be logged as
warnings during install).

[tokens]: https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line
[tokens]:
https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line
59 changes: 38 additions & 21 deletions docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

## add

Adds a subcomponent to the current component (or the component specified by the passed path).
Adds a subcomponent to the current component (or the component specified by the
passed path).

### Usage

Expand All @@ -12,10 +13,14 @@ $ fab add <component-name> --source <component-source> [--type component] [--met

Where:

- `source` specifies where the component lives (either a local path or remote http(s) endpoint)
- `type` specifies the type of component (`component` (default), `helm`, or `static`)
- `method` specifies the method that should be used to fetch the component (`git` (default))
- `path` specifies the path to the component that this subcomponent should be added to.
- `source` specifies where the component lives (either a local path or remote
http(s) endpoint)
- `type` specifies the type of component (`component` (default), `helm`, or
`static`)
- `method` specifies the method that should be used to fetch the component
(`git` (default))
- `path` specifies the path to the component that this subcomponent should be
added to.

### Example

Expand All @@ -25,19 +30,22 @@ $ fab add cloud-native --source https://github.com/timfpark/fabrikate-cloud-nati

## generate

Generates Kubernetes resource definitions from deployment definition in the current subtree.
Generates Kubernetes resource definitions from deployment definition in the
current subtree.

### Usage

```sh
$ fab generate <config1> <config2> ... <configN>
```

Where the generate command takes a list of the configurations that should be used to generate the resource
definitions for the deployment. These configurations should be specified in priority order. For example,
if you specified `prod azure east`, `prod`'s config would be applied first, and `azure`'s config
would only be applied if they did not conflict with `prod`. Likewise, `east`'s config would only be applied
if it did not conflict with `prod` or `azure`.
Where the generate command takes a list of the configurations that should be
used to generate the resource definitions for the deployment. These
configurations should be specified in priority order. For example, if you
specified `prod azure east`, `prod`'s config would be applied first, and
`azure`'s config would only be applied if they did not conflict with `prod`.
Likewise, `east`'s config would only be applied if it did not conflict with
`prod` or `azure`.

### Example

Expand All @@ -47,9 +55,10 @@ $ fab generate prod azure east

## install

Installs all of the remote components specified in the current deployment tree locally, iterating the
component subtree from the current directory to do so. Required to be executed before generate (if needed), such
that Fabrikate has all of the dependencies locally to use to generate the resource manifests.
Installs all of the remote components specified in the current deployment tree
locally, iterating the component subtree from the current directory to do so.
Required to be executed before generate (if needed), such that Fabrikate has all
of the dependencies locally to use to generate the resource manifests.

#### Example

Expand All @@ -75,7 +84,8 @@ $ fab remove cloud-native

## set

Sets a config value for a component for a particular config environment in the Fabrikate definition.
Sets a config value for a component for a particular config environment in the
Fabrikate definition.

### Usage

Expand All @@ -89,19 +99,24 @@ $ fab set --environment <name> [--subcomponent <subcomponent name>] [--file <inp
$ fab set --environment prod data.replicas=4 username="ops"
```

Sets the value of 'data.replicas' equal to 4 and 'username' equal to 'ops' in the 'prod' config for the current component.
Sets the value of 'data.replicas' equal to 4 and 'username' equal to 'ops' in
the 'prod' config for the current component.

```sh
$ fab set --subcomponent "myapp" endpoint="east-db"
```

Sets the value of 'endpoint' equal to 'east-db' in the 'common' config (the default) for subcomponent 'myapp'.
Sets the value of 'endpoint' equal to 'east-db' in the 'common' config (the
default) for subcomponent 'myapp'.

```sh
$ fab set --subcomponent "myapp.mysubcomponent" data.replicas=5
```

Sets the subkey "replicas" in the key 'data' equal to 5 in the 'common' config (the default) for the subcomponent 'mysubcomponent' of the subcomponent 'myapp', but raises an error via the --no-new-config-keys switch if doing so would create new config.
Sets the subkey "replicas" in the key 'data' equal to 5 in the 'common' config
(the default) for the subcomponent 'mysubcomponent' of the subcomponent 'myapp',
but raises an error via the --no-new-config-keys switch if doing so would create
new config.

```sh
$ fab set --subcomponent "myapp.mysubcomponent" data.replicas=5 --no-new-config-keys
Expand All @@ -112,7 +127,8 @@ $ fab set --subcomponent "myapp.mysubcomponent" data.replicas=5 --no-new-config-
Note:

- `.` in keys is not supported
- List values are not supported; they will be converted to raw strings (`[1, 2, 3]` will convert to `"[1 2 3]"`)
- List values are not supported; they will be converted to raw strings
(`[1, 2, 3]` will convert to `"[1 2 3]"`)

my-config.yaml:

Expand All @@ -129,8 +145,9 @@ it: has many keys
$ fab set --subcomponent "myapp.mysubcomponent" --file my-config-file.yaml
```

will set the the config for the subcomponent "mysubcomponent" of the "myapp" component to the contents of my-config.yaml.
This is the equivalent of executing:
will set the the config for the subcomponent "mysubcomponent" of the "myapp"
component to the contents of my-config.yaml. This is the equivalent of
executing:

```sh
$ fab set --subcomponent "myapp.mysubcomponent" this.is.my.config=file this.is.my.foo=bar it="has many keys"
Expand Down
78 changes: 55 additions & 23 deletions docs/component.md
Original file line number Diff line number Diff line change
@@ -1,49 +1,75 @@
# Component Object Model

A deployment definition in Fabrikate is specified via one or more component.yaml/json files. Each of these file contains a
specification of a component with the following schema:
A deployment definition in Fabrikate is specified via one or more
component.yaml/json files. Each of these file contains a specification of a
component with the following schema:

- `name`: A free form text name for this component. This name is used to refer to the component in [config specifications](./config.md).
- `name`: A free form text name for this component. This name is used to refer
to the component in [config specifications](./config.md).

- `type`: Method used to install and generate the resource needed for this particular component. Currently, `static` (file based), `helm` (helm based), and `component` (default) are supported values.
- `type`: Method used to install and generate the resource needed for this
particular component. Currently, `static` (file based), `helm` (helm based),
and `component` (default) are supported values.

- if `type: component`: the component itself does not contain any manifests to generate, but is a container for other components.
- if `type: helm`: `source` is the helm repository URL and `path` is the name of the target chart; `helm template` will be called on the component during `fab gen`.
- if `type: static`: the component holds raw kubernetes manifest files in `path`.
- if `type: component`: the component itself does not contain any manifests to
generate, but is a container for other components.
- if `type: helm`: `source` is the helm repository URL and `path` is the name
of the target chart; `helm template` will be called on the component during
`fab gen`.
- if `type: static`: the component holds raw kubernetes manifest files in
`path`.

- `method`: The method by which this component is sourced. Currently, only `git`, `helm`, and `local` are supported values.
- `method`: The method by which this component is sourced. Currently, only
`git`, `helm`, and `local` are supported values.

- if `method: git`: Tells fabrikate to `git clone <source>`.
- if `method: helm`: Tells fabrikate to `helm fetch <path>` from the `source` helm repo.
- if `method: local`: Tells fabrikate to use the host filesystem as a means to find the component.
- if `method: helm`: Tells fabrikate to `helm fetch <path>` from the `source`
helm repo.
- if `method: local`: Tells fabrikate to use the host filesystem as a means to
find the component.

- `source`: The source for this component.

- if `method: git`: A URL for a Git repository (the url you would call `git clone` on).
- if `method: helm`: A URL to a helm repository (the url you would call `helm repo add` on).
- if `method: git`: A URL for a Git repository (the url you would call
`git clone` on).
- if `method: helm`: A URL to a helm repository (the url you would call
`helm repo add` on).
- if `method: local`: A local path to specify a local filesystem component.

- `path`: For some components, like ones generated with `helm`, the desired target of the component might not be located at the root of the repo. Path enables you to specify the relative `path` to this target from the root of the `source`.
- `path`: For some components, like ones generated with `helm`, the desired
target of the component might not be located at the root of the repo. Path
enables you to specify the relative `path` to this target from the root of the
`source`.

- if `method: git`: the subdirectory of the component in the git repo specified in `source`.
- if `method: helm`: the name of the chart to install the repo specified in `source`.
- if `method: local`: the subdirectory on host filesystem where the component is located.
- if `method: git`: the subdirectory of the component in the git repo
specified in `source`.
- if `method: helm`: the name of the chart to install the repo specified in
`source`.
- if `method: local`: the subdirectory on host filesystem where the component
is located.

- `version`: For git `method` components, this specifies a specific commit SHA hash that the component should be locked to, enabling you to lock the component to a consistent version.
- `version`: For git `method` components, this specifies a specific commit SHA
hash that the component should be locked to, enabling you to lock the
component to a consistent version.

- if `method: git`: a specific commit to checkout from the repository.
- if `method: helm`: noop
- if `method: local`: noop

- `branch`: For git `method` components, this specifies the branch that should be checked out after the git `source` is cloned.
- `branch`: For git `method` components, this specifies the branch that should
be checked out after the git `source` is cloned.

- if `method: git`: a specific branch to checkout from the repository.
- if `method: helm`: noop
- if `method: local`: noop

- `hooks`: Hooks enable you to execute one or more shell commands before or after the following component lifecycle events: `before-install`, `before-generate`, `after-install`, `after-generate`.
- `hooks`: Hooks enable you to execute one or more shell commands before or
after the following component lifecycle events: `before-install`,
`before-generate`, `after-install`, `after-generate`.

- `subcomponents`: Zero or more subcomponents that define how to build the resource manifests that make up this component. These subcomponents are components themselves and have exactly the same schema as above.
- `subcomponents`: Zero or more subcomponents that define how to build the
resource manifests that make up this component. These subcomponents are
components themselves and have exactly the same schema as above.

## Examples

Expand Down Expand Up @@ -79,15 +105,19 @@ subcomponents:
### Istio
This [component specification](https://github.com/evanlouie/fabrikate-istio) utilizes hooks to download and unpack an Istio release and then reference it with a local path.
This [component specification](https://github.com/evanlouie/fabrikate-istio)
utilizes hooks to download and unpack an Istio release and then reference it
with a local path.
```yaml
name: istio
generator: helm
path: "./tmp/istio-1.1.2/install/kubernetes/helm/istio"
hooks:
before-install:
- curl -Lv https://github.com/istio/istio/releases/download/1.1.2/istio-1.1.2-linux.tar.gz -o istio.tar.gz
- curl -Lv
https://github.com/istio/istio/releases/download/1.1.2/istio-1.1.2-linux.tar.gz
-o istio.tar.gz
- mkdir -p tmp
- tar xvf istio.tar.gz -C tmp
after-install:
Expand All @@ -103,7 +133,9 @@ subcomponents:
### Jaeger
This [component specification](https://github.com/bnookala/fabrikate-jaeger) is specified in JSON and utilizes the `method: helm` feature to `helm fetch` the jaeger chart from the incubator helm repo.
This [component specification](https://github.com/bnookala/fabrikate-jaeger) is
specified in JSON and utilizes the `method: helm` feature to `helm fetch` the
jaeger chart from the incubator helm repo.

```json
{
Expand Down
56 changes: 47 additions & 9 deletions docs/config.md
Original file line number Diff line number Diff line change
@@ -1,25 +1,58 @@
# Config Definitions

Configuration files in Fabrikate allow you to define the structure of your deployment once via [components](./component.md) while enabling elements of it to vary across different environments like QA, staging, and production or across on-prem and a public cloud -- or both.
Configuration files in Fabrikate allow you to define the structure of your
deployment once via [components](./component.md) while enabling elements of it
to vary across different environments like QA, staging, and production or across
on-prem and a public cloud -- or both.

By convention, configuration is placed into a directory called `config` with the name of the environment that it applies to. Also by convention, if a `common.yaml` (or `common.json`) config definition exists, it is applied globally as config.
By convention, configuration is placed into a directory called `config` with the
name of the environment that it applies to. Also by convention, if a
`common.yaml` (or `common.json`) config definition exists, it is applied
globally as config.

The schema for these config definitions is fairly simple:

- `config`: A set of configuration values for the component in the parent directory that is intended to be used in conjunction with a generator. For example, with a Helm generator, these configuration values will be applied through a `values.yaml` file to the helm template specified.
- `config`: A set of configuration values for the component in the parent
directory that is intended to be used in conjunction with a generator. For
example, with a Helm generator, these configuration values will be applied
through a `values.yaml` file to the helm template specified.
- `namespace`: The namespace that should be applied for this component.
- `injectNamespace`: Directs Fabrikate to inject the specified namespace into every resource manifest generated for this component. This is intended for generators that don't support applying namespaces or where the template for the generator doesn't parameterize the namespace such that it is user accessible.
- `subcomponents`: A set of key/value pairs for the subcomponents of this component that specify the configuration for those components. Each of the values of these keys is a config definition in its own right and has the same schema as this config definition.
- `injectNamespace`: Directs Fabrikate to inject the specified namespace into
every resource manifest generated for this component. This is intended for
generators that don't support applying namespaces or where the template for
the generator doesn't parameterize the namespace such that it is user
accessible.
- `subcomponents`: A set of key/value pairs for the subcomponents of this
component that specify the configuration for those components. Each of the
values of these keys is a config definition in its own right and has the same
schema as this config definition.

Configuration in Fabrikate is collected from the top of the hierarchy down, meaning if a config definition lower in the hierarchy specifies a value for a key of configuration that has been already collected, the configuration provided higher in the hierarchy wins out. The reasoning behind this is because configuration higher in the hierarchy has a higher level of context over how the portions of the deployment definition should work with each other.
Configuration in Fabrikate is collected from the top of the hierarchy down,
meaning if a config definition lower in the hierarchy specifies a value for a
key of configuration that has been already collected, the configuration provided
higher in the hierarchy wins out. The reasoning behind this is because
configuration higher in the hierarchy has a higher level of context over how the
portions of the deployment definition should work with each other.

Configuration can (and is encouraged to be) factored out into its individual concerns. For example, to compose a set of resource manifests for a Production environment in East US in Azure, you might factor your configuration into `prod`, `east`, and `azure` configuration files such that when you need to build a Production environment in West US, you can simply swap out the `east` config for a `west` config.
Configuration can (and is encouraged to be) factored out into its individual
concerns. For example, to compose a set of resource manifests for a Production
environment in East US in Azure, you might factor your configuration into
`prod`, `east`, and `azure` configuration files such that when you need to build
a Production environment in West US, you can simply swap out the `east` config
for a `west` config.

## Examples

### Jaeger

In this [config definition](https://github.com/bnookala/fabrikate-jaeger/blob/master/config/common.yaml), configuration is applied to the subcomponent `jaeger` for `collector.annotations.sidecar.istio.io/inject` with the value `false` which will be passed to the helm `values.yaml` file that is applied to this helm chart. The namespace `jaeger` is also injected into the namespace for every resource manifest generated as the helm chart templates written for Jaeger were not parameterized to inject a namespace.
In this
[config definition](https://github.com/bnookala/fabrikate-jaeger/blob/master/config/common.yaml),
configuration is applied to the subcomponent `jaeger` for
`collector.annotations.sidecar.istio.io/inject` with the value `false` which
will be passed to the helm `values.yaml` file that is applied to this helm
chart. The namespace `jaeger` is also injected into the namespace for every
resource manifest generated as the helm chart templates written for Jaeger were
not parameterized to inject a namespace.

```yaml
config:
Expand All @@ -35,7 +68,12 @@ subcomponents:
### Istio
In this [config definition](https://github.com/evanlouie/fabrikate-istio/blob/master/config/common.yaml) we are applying the namespace `istio-system` and also applying the config `global.k8sIngress.enable`: `true` in the `values.yaml` file that is applied to the helm chart. It also applies the namespace `istio-system` to the subcomponent `istio-crd`.
In this
[config definition](https://github.com/evanlouie/fabrikate-istio/blob/master/config/common.yaml)
we are applying the namespace `istio-system` and also applying the config
`global.k8sIngress.enable`: `true` in the `values.yaml` file that is applied to
the helm chart. It also applies the namespace `istio-system` to the subcomponent
`istio-crd`.

```yaml
namespace: istio-system
Expand Down
Loading

0 comments on commit 2ab2775

Please sign in to comment.