Skip to content

Commit 4d94cd8

Browse files
author
vaishk
committed
adding CRAFT docs
1 parent 8baae33 commit 4d94cd8

File tree

18 files changed

+634
-0
lines changed

18 files changed

+634
-0
lines changed

‎docs/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Running mdBook
2+
Docs are served using mdBook. If you want to test changes to the docs locally, follow these directions:
3+
4+
* Follow the instructions at https://github.com/rust-lang-nursery/mdBook#installation to install mdBook.
5+
* Run mdbook serve
6+
* Visit http://localhost:3000
7+
8+
# Steps to Deploy
9+
Currently we are using Github Pages to deploy our docs. To send changes to the docs
10+
* Run `mdbook build -d /tmp/craft-doc`
11+
* `mv /tmp/craft-doc .`
12+
* Send the Pull Request to `gh-pages`

‎docs/book.toml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[book]
2+
authors = ["salesforce"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"
6+
title = "CRAFT"

‎docs/src/.DS_Store‎

6 KB
Binary file not shown.

‎docs/src/README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Introduction to CRAFT
2+
3+
CRAFT (Custom Resource Abstraction and Fabrication Tool) declares Kubernetes operators in a robust, idempotent, and generic way for any resource.
4+
5+
Creating a Kubernetes operator requires domain knowledge of abstraction and expertise in Kubernetes and Golang. With CRAFT you can create operators without a dependent layer and in the language of your choice!
6+
7+
Declare your custom resource in JSON files and let CRAFT generate all the files needed to deploy your operator into the cluster. CRAFT Wordpress operator generates 571 lines of code for you, a task that otherwise takes a few months to complete.
8+
9+
Reduce your workload by automating resource reconciliation with CRAFT to ensure your resource stays in its desired state. CRAFT also performs schema validations on your custom resource while creating the operator. Through automated reconciliation and schema validations, CRAFT achieves the objectives listed in the [Kubernetes Architecture Design Proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md#bespoke-application-deployment).
10+
11+
## Advantages of using Craft
12+
13+
1. **Easy onboarding** : Create an operator in your language of choice.
14+
2. **Segregation of duties** : Developers can work in the docker file while the Site Reliability or DevOps engineer can declaratively configure the operator.
15+
3. **Control access** : Control which users have access to the operator resources.
16+
4. **Versioning and API interface** : Work on a different version of the operator or resource than your users.
17+
5. **Save time** : Get schema and input validation feedback before runtime.
18+
6. **Automated reconciliation** : Automate resource reconciliation to lower your maintenance workload.
19+
7. **Dependent teams work independently** : Dependent teams can automate independently and create abstraction layers on top of your abstraction.
20+
21+
## Built with
22+
23+
CRAFT is built with open source projects Kubebuilder and Operatify:
24+
* **Kubebuilder** : CRAFT augments the operator skeleton generated by Kubebuilder with custom resource definitions and controller capabilities.
25+
* **Operatify** : CRAFT leverages Operatify’s automated reconciliation capabilities.

‎docs/src/SUMMARY.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Summary
2+
3+
* [Introduction](README.md)
4+
* [Quickstart](quick_setup/README.md)
5+
* [Wordpress Operator Tutorial](tutorial/README.md)
6+
* [Step 1: Create the Custom Resource Files and Docker Image](tutorial/step1.md)
7+
* [Controller.json](tutorial/controller_file.md)
8+
* [Resource.json](tutorial/resource_file.md)
9+
* [Resource DockerFile](tutorial/resource_dockerfile.md)
10+
* [CRUD operations Exit Codes](tutorial/docker_exit_codes.md)
11+
* [Step 2: Create an Operator](tutorial/step2.md)
12+
* [Namespace.yaml](tutorial/namespace_file.md)
13+
* [Operator.yaml](tutorial/operator_file.md)
14+
* [Step3: Deploy Operator onto the cluster](tutorial/deploy_operator.md)
15+
* [Operator source code](operator_source_code/README.md)
16+
* [Controllers and Reconcilers](operator_source_code/controller_reconciler.md)
17+

‎docs/src/operator_source_code/README.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Where is the Operator Code?
2+
3+
The source code for the operator is stored in the `$GOPATH/src` path.
4+
```
5+
$ cd $GOPATH/src/wordpress
6+
$ ls
7+
8+
```
9+
10+
The folder contains all the files required to run an operator like the configurations, API files, controllers, reconciliation files, main files, etc. All these files contain information about the operator and it's runtime characteristics, such as the CRUD logic, reconciliation frequency, etc. These files can be classified in four sections:
11+
12+
1. Build infrastructure.
13+
14+
2. Launch Configuration.
15+
16+
3. Entry Point
17+
18+
4. Controllers and Reconciler.
19+
20+
CRAFT creates these files when you create an operator. This saves you a few weeks of effort to write and connect your operator.
21+
22+
## Build Infrastructure
23+
24+
These files are used to build the operator:
25+
- go.mod : A Go module for the project that lists all the dependencies.
26+
- Makefile : File makes targets for building and deploying the controller and reconciler.
27+
- PROJECT : Kubebuilder metadata for scaffolding new components.
28+
- DockerFile : File with instructions on running the operator. Specifies the docker entrypoint for the operator.
29+
30+
31+
## Launch Configuration
32+
33+
34+
The launch configurations are in the config/ directory. It holds the CustomResourceDefinitions, RBAC configuration, and WebhookConfigurations. Each folder in config/ contains a refactored part of the launch configuration.
35+
- `config/default` contains a Kustomize base for launching the controller with standard configurations.
36+
- `config/manager` can be used to launch controllers as pods in the cluster
37+
- `config/rbac` contains permissions required to run your controllers under their own service account.
38+
39+
40+
## Entry point
41+
42+
The basic entry point for the operator is in the main.go file. This file can be used to:
43+
- Set up flags for metrics.
44+
- Initialise all the controller parameters, including the reconciliation frequency and the parameters we received from controller.json and resource.json
45+
- Instantiate a manager to keep track of all the running controllers and clients to the API server.
46+
- Run a manager that runs all of the controllers and keeps track of them until it receives a shutdown signal when it stops all of the controllers.
47+

‎docs/src/operator_source_code/controller_reconciler.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Controllers and Reconciler
2+
3+
A controller is the core of Kubernetes and operators. A controller ensures that, for any given object, the actual state of the world (both the cluster state, and potentially external state like running containers for Kubelet or loadbalancers for a cloud provider) matches the desired state in the object. Each controller focuses on one root API type but may interact with other API types.
4+
5+
A reconciler tracks changes to the root API type, checks and updates changes in the operator image at controller-runtime. It runs an operation and returns an exit code, and through this process it checks if reconciliation is needed and determines the frequency for reconciliation. Based on the exit code, the next operation is added to the controller queue.
6+
7+
These are the 14 exit codes that a reconciler can return:
8+
9+
```
10+
## ExitCode to state mapping
11+
201: "Succeeded", // create or update
12+
202: "AwaitingVerification", // create or update
13+
203: "Error", // create or update
14+
211: "Ready", // verify
15+
212: "InProgress", // verify
16+
213: "Error", // verify
17+
214: "Missing", // verify
18+
215: "UpdateRequired", // verify
19+
216: "RecreateRequired", // verify
20+
217: "Deleting", // verify
21+
221: "Succeeded", // delete
22+
222: "InProgress", // delete
23+
223: "Error", // delete
24+
224: "Missing", // delete
25+
```
26+

‎docs/src/quick_setup/README.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Quick Setup
2+
## Prerequisites
3+
4+
* [Go](https://golang.org/dl/) version v1.13+
5+
* [Docker](https://docs.docker.com/get-docker/) version 17.03+
6+
* [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) version v1.11.3+
7+
* [Kustomize](https://kubernetes-sigs.github.io/kustomize/installation/) version v3.1.0+
8+
* [Kubebuilder](https://book.kubebuilder.io/quick-start.html#installation) version v2.0.0+
9+
10+
## Installation
11+
12+
The latest version of CRAFT can be found [here](https://github.com/salesforce/craft/releases/). Extract it into **/usr/local** directory.
13+
14+
```
15+
sudo tar -C /usr/local -xzf ~/Downloads/craft.tar.gz
16+
```
17+
18+
Note: Replace **/Downloads/craft.tar.gz** with the directory where you downloaded the latest version of CRAFT.
19+
20+
Next, add the /usr/local/craft/bin directory to your PATH environment variable.
21+
22+
```
23+
export PATH=$PATH:/usr/local/craft/bin
24+
```
25+
26+
You can also add CRAFT to your PATH environment variable permanently.
27+
28+
```
29+
sudo vim /etc/paths
30+
```
31+
32+
Add the line **/usr/local/craft/bin** at the end of the file and save the file.
33+
34+
## Create a CRAFT Application
35+
36+
From the command line, **cd** into a directory where you'd like to store your CRAFT application and run this command:
37+
38+
```
39+
craft init
40+
```
41+
42+
This will initiate a CRAFT application in your current directory and create the following skeleton files:
43+
44+
- controller.json: This file holds Custom Resource Definition (CRD) information like group, domain, operator image, and reconciliation frequency.
45+
- resource.json: This file contains the schema information for validating inputs while creating the CRD.
46+
47+
##Next Steps
48+
49+
Follow the Wordpress operator tutorial to understand how to use CRAFT to create and deploy an operator into a cluster. This deep-dive tutorial demonstrates the entire scope and scale of a CRAFT application.

‎docs/src/tutorial/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Tutorial : Wordpress Operator
2+
Unlike most tutorials who start with some really contrived setup, or some toy application that gets the basics across, this tutorial will take you through the full extent of the CRAFT application and how it is useful. We start off simple and in the end, build something pretty full-featured and meaningful, namely, an operator for the Wordpress application.
3+
4+
The job of the Wordpress operator is to host the Wordpress application and perform operations given by the user on the cluster. It reconciles regularly, checking for updates in the resource and therefore, can be termed as level-triggered.
5+
6+
We will see how the controller.json and resource.json required to run the wordpress operator have been developed. Then, we'll see how to use CRAFT to create the operator and deploy it onto the cluster.
7+
8+
The config files required to create the operator are already present in `example/wordpress-operator`
9+
10+
Let's go ahead and see how we have created our files for the wordpress application to understand and generalise this process for any application. First, we start with the controller.json file in the next section.
11+

‎docs/src/tutorial/controller_file.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Controller.json
2+
3+
Custom Resource Definition (CRD) information like the domain, group, image, repository, etc. are stored in the controller.json file. This skeleton file for controller.json is created when you [create a CRAFT application in quickstart](quick_setup/README.md):
4+
5+
"group": "",
6+
"resource": "",
7+
"repo": "",
8+
"domain": "",
9+
"namespace": "",
10+
"version": "",
11+
"operator_image": "",
12+
"image": "",
13+
"imagePullSecrets": "",
14+
"imagePullPolicy": "",
15+
"cpu_limit": "",
16+
"memory_limit": "",
17+
"vault_addr": "",
18+
"runOnce": "",
19+
"reconcileFreq": ""
20+
21+
This table explains the controller.json attributes:
22+
23+
| Attribute | Description | | | |
24+
|------------------|--------------------------------------------------------------------------------------------------------------------------------|---|---|---|
25+
| group | See the Kubernetes API Concepts page for more information. | | | |
26+
| resource | | | | |
27+
| namespace | | | | |
28+
| version | | | | |
29+
| repo | The repo where you want to store the operator template. | | | |
30+
| domain | The domain web address for this project. | | | |
31+
| operator_image | The docker registry files used to push operator image into docker. | | | |
32+
| image | The docker registry files used to push resource image into docker. | | | |
33+
| imagePullSecrets | Restricted data to be stored in the operator like access, permissions, etc. | | | |
34+
| imagePullPolicy | Method of updating images. Default pull policy is IfNotPresent causes Kubelet to skip pulling an image if one already exists. | | | |
35+
| cpu_limit | CPU limit allocated to the operator created. | | | |
36+
| memory_limit | Memory limit allocated to the operator created. | | | |
37+
| vault_addr | Address of the vault. | | | |
38+
| runOnce | If set to 0 reconciliation stops. If set to 1, reconciliation runs according to the specified frequency. | | | |
39+
| reconcileFreq | Frequency interval (in minutes) between two reconciliations. | | | |
40+
41+
42+
Here’s an example of a controller.json file for the Wordpress operator:
43+
44+
```
45+
{
46+
"group": "wordpress",
47+
"resource": "WordpressAPI",
48+
"repo": "wordpress",
49+
"domain": "salesforce.com",
50+
"namespace": "default",
51+
"version": "v1",
52+
"operator_image": "ops0-artifactrepo1-0-prd.data.sfdc.net/cco/wordpress-operator",
53+
"image": "ops0-artifactrepo1-0-prd.data.sfdc.net/cco/wordpress:latest",
54+
"imagePullSecrets": "registrycredential",
55+
"imagePullPolicy": "IfNotPresent",
56+
"cpu_limit": "500m",
57+
"memory_limit": "200Mi",
58+
"vault_addr": "http://10.215.194.253:8200"
59+
}
60+
```
61+
62+

0 commit comments

Comments
 (0)