Skip to content

Commit ec2c14c

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #1008 from camilamacedo86/quick
doc(quick) : improvements in order to improve the experience of new users
2 parents 85b2863 + a986054 commit ec2c14c

File tree

2 files changed

+114
-24
lines changed

2 files changed

+114
-24
lines changed

‎docs/book/src/cronjob-tutorial/running.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,8 @@ Now that we know it's working, we can run it in the cluster. Stop the
6161
`make run` invocation, and run
6262

6363
```bash
64-
make docker-build docker-push IMG=<some-registry>/controller
65-
make deploy IMG=<some-registry>/controller
64+
make docker-build docker-push IMG=<some-registry>/<project-name>:tag
65+
make deploy IMG=<some-registry>/<project-name>:tag
6666
```
6767

6868
If we list cronjobs again like we did before, we should see the controller

‎docs/book/src/quick-start.md‎

Lines changed: 112 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,14 @@ This Quick Start guide will cover:
77
- [Running locally](#test-it-out-locally)
88
- [Running in-cluster](#run-it-on-the-cluster)
99

10+
## Prerequisites
11+
12+
- [go](https://golang.org/dl/) version v1.12+.
13+
- [docker](https://docs.docker.com/install/) version 17.03+.
14+
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) version v1.11.3+.
15+
- [kustomize](https://sigs.k8s.io/kustomize/docs/INSTALL.md) v3.1.0+
16+
- Access to a Kubernetes v1.11.3+ cluster.
17+
1018
## Installation
1119

1220
Install [kubebuilder](https://sigs.k8s.io/kubebuilder):
@@ -24,64 +32,139 @@ sudo mv /tmp/kubebuilder_2.0.1_${os}_${arch} /usr/local/kubebuilder
2432
export PATH=$PATH:/usr/local/kubebuilder/bin
2533
```
2634

27-
You can also install a KubeBuilder master snapshot from
28-
`https://go.kubebuilder.io/dl/latest/${os}/${arch}`.
35+
<aside class="note">
36+
<h1>Using master branch</h1>
37+
38+
Also, you can install a master snapshot from `https://go.kubebuilder.io/dl/latest/${os}/${arch}`.
2939

30-
Install [kustomize](https://sigs.k8s.io/kustomize/docs/INSTALL.md) v3.1.0+
40+
</aside>
3141

3242
## Create a Project
3343

34-
Initialize a new project and Go module for your controllers:
44+
Create a directory, and then run the following command inside of it to initialize a new project:
3545

3646
```bash
3747
kubebuilder init --domain my.domain
3848
```
3949

50+
<aside class="note">
51+
<h1>Not in $GOPATH</h1>
52+
4053
If you're not in `GOPATH`, you'll need to run `go mod init <modulename>`
41-
in order to tell kubebuilder and Go the base import path of your module.
54+
in order to tell kubebuilder and Go the base import path of your module.
55+
56+
</aside>
57+
58+
<aside class="note">
59+
<h1>Go package issues</h1>
60+
61+
Ensure that you activate the module support by running `$ export GO111MODULE=on`
62+
to solve issues as `cannot find package ... (from $GOROOT)`.
63+
64+
</aside>
65+
4266

4367
## Create an API
4468

45-
Create a new API group-version called `webapp/v1`, and a kind `Guestbook`
46-
in that API group-version:
69+
Run the following command to create a new API (group/version) as `webapp/v1` and the new Kind(CRD) `Guestbook` on it:
4770

4871
```bash
4972
kubebuilder create api --group webapp --version v1 --kind Guestbook
5073
```
5174

52-
This will create the files `api/v1/guestbook_types.go` and
53-
`controller/guestbook_controller.go` for you to edit.
75+
<aside class="note">
76+
<h1>Press Options</h1>
77+
78+
If you press `y` for Create Resource [y/n] and for Create Controller [y/n] then this will create the files `api/v1/guestbook_types.go` where the API is defined
79+
and the `controller/guestbook_controller.go` where the reconciliation business logic is implemented for this Kind(CRD).
80+
81+
</aside>
82+
83+
84+
**OPTIONAL:** Edit the API definition and the reconciliation business
85+
logic. For more info see [Designing an API](/cronjob-tutorial/api-design.md) and [What's in
86+
a Controller](cronjob-tutorial/controller-overview.md).
87+
88+
<details><summary>Click here to see an example. `(api/v1/guestbook_types.go)` </summary>
89+
<p>
90+
91+
```go
92+
// GuestbookSpec defines the desired state of Guestbook
93+
type GuestbookSpec struct {
94+
// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
95+
// Important: Run "make" to regenerate code after modifying this file
96+
97+
// Quantity of instances
98+
// +kubebuilder:validation:Minimum=1
99+
// +kubebuilder:validation:Maximum=10
100+
Size int32 `json:"size"`
101+
102+
// Name of the ConfigMap for GuestbookSpec's configuration
103+
// +kubebuilder:validation:MaxLength=15
104+
// +kubebuilder:validation:MinLength=1
105+
ConfigMapName string `json:"configMapName"`
106+
107+
// +kubebuilder:validation:Enum=Phone,Address,Name
108+
Type string `json:"alias,omitempty"`
109+
110+
// TLS policy of Guestbook nodes
111+
TLS *TLSPolicy `json:"TLS,omitempty"`
112+
}
113+
114+
// GuestbookStatus defines the observed state of Guestbook
115+
type GuestbookStatus struct {
116+
// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
117+
// Important: Run "make" to regenerate code after modifying this file
118+
119+
// GuestbookStatus is the set of Guestbook node specific statuses: Active or Standby
120+
GuestbookStatus GuestbookStatus `json:"guestbookStatus"`
121+
122+
// Status of Guestbook Nodes
123+
Nodes []string `json:"nodes"`
124+
}
125+
126+
type GuestbookStatus struct {
127+
128+
// PodName of the active Guestbook node.
129+
Active string `json:"active"`
130+
131+
// PodNames of the standby Guestbook nodes.
132+
Standby []string `json:"standby"`
133+
}
134+
```
135+
136+
</p>
137+
</details>
54138

55-
**Optional:** Edit the API definition or the reconciliation business
56-
logic. For more on this see [What's in
57-
a Controller](cronjob-tutorial/controller-overview.md) and [Designing an
58-
API](/cronjob-tutorial/api-design.md).
59139

60-
## Test It Out Locally
140+
## Test It Out
61141

62142
You'll need a Kubernetes cluster to run against. You can use
63143
[KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or
64144
run against a remote cluster.
65145

146+
<aside class="note">
147+
<h1>Context Used</h1>
148+
66149
Your controller will automatically use the current context in your
67150
kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
68151

69-
Install the CRDs into the cluster:
152+
</aside>
70153

154+
Install the CRDs into the cluster:
71155
```bash
72156
make install
73157
```
74158

75159
Run your controller (this will run in the foreground, so switch to a new
76160
terminal if you want to leave it running):
77-
78161
```bash
79162
make run
80163
```
81164

82-
## Install Samples
165+
## Install Instances of Custom Resources
83166

84-
Create your samples (make sure to edit them first if you've changed the
167+
If you pressed `y` for Create Resource [y/n] then you created an (CR)Custom Resource for your (CRD)Custom Resource Definition in your samples (make sure to edit them first if you've changed the
85168
API definition):
86169

87170
```bash
@@ -93,16 +176,23 @@ kubectl apply -f config/samples/
93176
Build and push your image to the location specified by `IMG`:
94177

95178
```bash
96-
make docker-build docker-push IMG=<some-registry>/controller
179+
make docker-build docker-push IMG=<some-registry>/<project-name>:tag
97180
```
98181

99182
Deploy the controller to the cluster with image specified by `IMG`:
100183

101184
```bash
102-
make deploy IMG=<some-registry>/controller
185+
make deploy IMG=<some-registry>/<project-name>:tag
103186
```
104187

188+
<aside class="note">
189+
<h1>RBAC errors</h1>
190+
105191
If you encounter RBAC errors, you may need to grant yourself cluster-admin
106-
privileges:
192+
privileges or be logged in as admin. See [Prerequisites for using Kubernetes RBAC on GKE cluster v1.11.x and older][pre-rbc-gke] which may can be your case.
193+
194+
</aside>
195+
196+
Now, follow up the tutorial for you understanding better how it works and check an full example project working.
107197

108-
<!-- TODO(directxman12): fill this in -->
198+
[pre-rbc-gke]:https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control#iam-rolebinding-bootstrap

0 commit comments

Comments
 (0)