@npm-wharf/fabrik8
v1.9.6
Published
provision a new Kubernetes cluster and deploy software to it from a single API
Downloads
70
Readme
fabrik8
Provision and deploy cluster specifications from a single API.
What It's For
fabrik8
was designed to handle initialization of Kubernetes clusters with an initial, known-set of software using a mcgonagall
specification.
It works well in environments where you might want ephemeral clusters, clusters on demand (think single tenancy), or think about things like automation and disaster recovery a lot.
What It's Not For
fabrik8
is not a CD solution (at least not presently). It is not meant to be run continuously against the same target (it cannot guarantee 100% idempotence, but makes a best effort to be). Running fabrik8
multiple times may yield unexpected results. For CD solutions, see hikaru
.
Approach
fabrik8 uses kubeform
, mcgonagall
, and hikaru
to provision clusters, transform specifications, and deploy them to the newly created cluster.
Environment Variables
As noted in kubeform
, many of the environment variables are cloud provider specific and will only be necessary when using a specific provider.
| Variable | Description | Default |
|:-:|---|---|
| KUBE_SERVICE
| The backing service to use for the request | 'GKE'
|
| GOOGLE_APPLICATION_CREDENTIALS
| Path to Google API credentials file | ''
|
| GOOGLE_ORGANIZATION_ID
| Google Organization Id to create projects under | ''
|
| GOOGLE_BILLING_ID
| Google Billing Account Id to associate with project | ''
|
API
initialize(cluster, specification, data|onData)
The initialize
call requires three arguments and returns a promise.
cluster
This will be the same as the kubeform
cluster specification (not repeated here).
specification
The specification argument must either be a file path to the spec or a URL to the GitHub repo where the mcgonagall specification is located.
data|onData
The third argument can either be a hash of data required to satisfy tokens present in the specification, or a function that is passed a list of tokens required by the specification. If a function is provided, the result expected is a promise providing a hash of data.
function getTokens (tokenList) {
// return token hash as a promise
return Promise.resolve({
tokenName: tokenValue
})
}
To control how cluster data will be merged with the mcgonagall specification data, the hash should include a function named onCluster
. It will be passed the cluster information returned from kubeform
and the data. The signature is:
function onCluster (data, clusterInfo) {
// assign new properties to data from clusterInfo as needed
data.someValue = clusterInfo.someSourceValue
}
Without passing this function, all cluster details will be set as children of a .cluster
property.
Return
Returns the cluster information from kubeform
and the data used to satisfy the specification (under the property specData
).
The expectation is that this information will be stored for future retrieval when interacting with the cluster. fabrik8
does not do anything beyond coordinate calls between libraries in order to simplify creation of fully functional
It is recommended that sensitive data (like the Kubernetes admin password) is stored separately in Vault or encrypted before storage.
CLI
A CLI is also provided for fabrik8
that allows you to invoke the API from the command line:
fabrik8 create [--name name] [--url url] --spec ./path/to/spec
Creates a full cluster, reading defaults and existing configuration securely from centralized cluster-info. The only options that are required are configuration for cluster-info, a name or cluster url, and the path to a McGonagall specification. If re-running, only a name is required -- options will be re-read from cluster-info.
--url
,-u
the url of the cluster you wish to create, e.g.mycluster.npme.io
--name
,-n
the name of the cluster. Can be inferred from the url--domain
the domain of the cluster. Can be inferred from the url. Defaults to whatever is specified in the cluster-info defaults, if only a name is provided.--projectId
the name of the gke project to use. Can be inferred from the cluster name--environment
the environment of the cluster, e.g. development, production--specification
,-m
,--spec
the path or URL to the mcgonagall specification--verbose
output verbose logging (status check output for hikaru)--vaultHost
the host of the vault server containing sensitive cluster information, auth data, and defaults. Can also be set through theVAULT_HOST
environment variable--vaultToken
an auth token for the vault server. Can also be set through theVAULT_TOKEN
environment variable--provider
the cloud provider to use, defaults toKUBE_SERVICE
environment variable orGKE
--output
,-o
file to write cluster-info to, for debugging
Values from the defaults can also be overridden as command line args, by prefixing the key with --arg-
, e.g. --arg-cluster.worker.memory 26GB
, or --arg-common.zones eu-central1-a
. Look at the cluster-info defaults for a list of values that can be overridden.
Command line arguments take precedence over saved cluster-info, which take precedence over default cluster-info. Cluster info-will be saved everytime you run fabrik8
, so re-running fabrik8 create
can be used to change values.