Skip to content

Commit cf2509a

Browse files
everettraveneverettraven
authored
Merge pull request #2 from everettraven/docs/initial-documentation
add initial documentation
2 parents 25304aa + 37ac152 commit cf2509a

File tree

9 files changed

+670
-2
lines changed

9 files changed

+670
-2
lines changed

‎README.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ Available Commands:
3333
Flags:
3434
--config string the filepath to load the check configurations from
3535
-h, --help help for crd-diff
36+
-o, --output string the format the output should take when incompatibilities are identified. May be one of plaintext, json, yaml (default "plaintext")
3637

3738
Use "crd-diff [command] --help" for more information about a command.
3839
```
@@ -54,5 +55,7 @@ crd-diff kube://memcacheds.cache.example.com file://crd.yaml
5455

5556
`crd-diff` can be installed by running:
5657
```sh
57-
go install github.com/everettraven/crd-diff@latest
58+
go install github.com/everettraven/crd-diff@{revision}
5859
```
60+
61+
Replace `{revision}` with a tag, commit, or `latest` to build and install the tool from source at that particular revision.

‎docs/.nojekyll

Whitespace-only changes.

‎docs/README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# crd-diff
2+
`crd-diff` is a CLI tool for comparing Kubernetes `CustomResourceDefinition` resources (CRDs) for differences.
3+
It checks for incompatible changes to help:
4+
- Cluster administrators protect CRDs on their clusters from breaking changes
5+
- GitOps practitioners prevent CRDs with breaking changes being committed
6+
- Developers of Kubernetes extension identify when changes to their CRDs are incompatible

‎docs/_sidebar.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
- [Home](/)
2+
- [Getting Started](getting-started.md)
3+
- [Validations](validations.md)
4+
- [Configuration](configuration.md)

‎docs/configuration.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Configuration
2+
`crd-diff` can be customized using a YAML configuration file.
3+
4+
By default, `crd-diff` uses this configuration:
5+
6+
```yaml
7+
checks:
8+
crd:
9+
scope:
10+
enabled: true
11+
existingFieldRemoval:
12+
enabled: true
13+
storedVersionRemoval:
14+
enabled: true
15+
version:
16+
sameVersion:
17+
enabled: true
18+
unhandledFailureMode: "Closed"
19+
enum:
20+
enabled: true
21+
removalEnforcement: Strict
22+
additionEnforcement: Strict
23+
default:
24+
enabled: true
25+
changeEnforcement: Strict
26+
removalEnforcement: Strict
27+
additionEnforcement: Strict
28+
required:
29+
enabled: true
30+
newEnforcement: Strict
31+
type:
32+
enabled: true
33+
changeEnforcement: Strict
34+
maximum:
35+
enabled: true
36+
additionEnforcement: Strict
37+
decreaseEnforcement: Strict
38+
maxItems:
39+
enabled: true
40+
additionEnforcement: Strict
41+
decreaseEnforcement: Strict
42+
maxProperties:
43+
enabled: true
44+
additionEnforcement: Strict
45+
decreaseEnforcement: Strict
46+
maxLength:
47+
enabled: true
48+
additionEnforcement: Strict
49+
decreaseEnforcement: Strict
50+
minimum:
51+
enabled: true
52+
additionEnforcement: Strict
53+
increaseEnforcement: Strict
54+
minItems:
55+
enabled: true
56+
additionEnforcement: Strict
57+
increaseEnforcement: Strict
58+
minProperties:
59+
enabled: true
60+
additionEnforcement: Strict
61+
increaseEnforcement: Strict
62+
minLength:
63+
enabled: true
64+
additionEnforcement: Strict
65+
increaseEnforcement: Strict
66+
servedVersion:
67+
enabled: true
68+
unhandledFailureMode: "Closed"
69+
ignoreConversion: false
70+
enum:
71+
enabled: true
72+
removalEnforcement: Strict
73+
additionEnforcement: Strict
74+
default:
75+
enabled: true
76+
changeEnforcement: Strict
77+
removalEnforcement: Strict
78+
additionEnforcement: Strict
79+
required:
80+
enabled: true
81+
newEnforcement: Strict
82+
type:
83+
enabled: true
84+
changeEnforcement: Strict
85+
maximum:
86+
enabled: true
87+
additionEnforcement: Strict
88+
decreaseEnforcement: Strict
89+
maxItems:
90+
enabled: true
91+
additionEnforcement: Strict
92+
decreaseEnforcement: Strict
93+
maxProperties:
94+
enabled: true
95+
additionEnforcement: Strict
96+
decreaseEnforcement: Strict
97+
maxLength:
98+
enabled: true
99+
additionEnforcement: Strict
100+
decreaseEnforcement: Strict
101+
minimum:
102+
enabled: true
103+
additionEnforcement: Strict
104+
increaseEnforcement: Strict
105+
minItems:
106+
enabled: true
107+
additionEnforcement: Strict
108+
increaseEnforcement: Strict
109+
minProperties:
110+
enabled: true
111+
additionEnforcement: Strict
112+
increaseEnforcement: Strict
113+
minLength:
114+
enabled: true
115+
additionEnforcement: Strict
116+
increaseEnforcement: Strict
117+
```

‎docs/getting-started.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Getting Started
2+
3+
## Installing `crd-diff`
4+
Currently, the only way to install the `crd-diff` tool is to use the `go install` command:
5+
6+
```sh
7+
go install github.com/everettraven/crd-diff@{revision}
8+
```
9+
10+
Replace `{revision}` with a tag, commit, or `latest` to build and install the tool from source at that particular revision.
11+
12+
## General Usage
13+
14+
```sh
15+
crd-diff is a tool for evaluating changes to Kubernetes CustomResourceDefinitions
16+
to help cluster administrators, gitops practitioners, and Kubernetes extension developers identify
17+
changes that might result in a negative impact to clusters and/or users.
18+
19+
Example use cases:
20+
Evaluating a change in a CustomResourceDefinition on a Kubernetes Cluster with one in a file:
21+
$ crd-diff kube://{crd-name} file://{filepath}
22+
23+
Evaluating a change from file to file:
24+
$ crd-diff file://{filepath} file://{filepath}
25+
26+
Evaluating a change from git ref to git ref:
27+
$ crd-diff git://{ref}?path={filepath} git://{ref}?path={filepath}
28+
29+
Usage:
30+
crd-diff <old> <new> [flags]
31+
crd-diff [command]
32+
33+
Available Commands:
34+
completion Generate the autocompletion script for the specified shell
35+
help Help about any command
36+
version installed version of crd-diff
37+
38+
Flags:
39+
--config string the filepath to load the check configurations from
40+
-h, --help help for crd-diff
41+
-o, --output string the format the output should take when incompatibilities are identified. May be one of plaintext, json, yaml (default "plaintext")
42+
43+
Use "crd-diff [command] --help" for more information about a command.
44+
```
45+
46+
The `<old>` and `<new>` arguments are required and should be the sourcing information for the old and new
47+
`CustomResourceDefinition` YAML
48+
49+
The supported sources are:
50+
51+
- `kube://{name}`
52+
- `git://{ref}?path={filepath}`
53+
- `file://{filepath}`
54+
55+
An example of using `crd-diff` to compare a `CustomResourceDefinition` on a Kubernetes cluster to the same one in a local file:
56+
57+
```sh
58+
crd-diff kube://memcacheds.cache.example.com file://crd.yaml
59+
```

‎docs/index.html

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<title>Document</title>
6+
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
7+
<meta name="description" content="Description">
8+
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
9+
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
10+
</head>
11+
<body>
12+
<div id="app"></div>
13+
<script>
14+
window.$docsify = {
15+
name: 'crd-diff',
16+
repo: 'https://www.github.com/everettraven/crd-diff',
17+
loadSidebar: true,
18+
subMaxLevel: 3,
19+
}
20+
</script>
21+
<!-- Docsify v4 -->
22+
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
23+
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
24+
</body>
25+
</html>

0 commit comments

Comments
 (0)