Skip to content

Commit 46f7379

Browse files
bharathi-tennetibharathi-tenneti
authored
doc: Ansible/Helm add api command Proposal for Operator SDK (#2641)
* doc: Ansible/Helm add api command Proposal for Operator SDK * Proposal template changes made * PR comments addressed * Typos fixed * suggestions applies * Broken ref fixed
1 parent 38e96f2 commit 46f7379

File tree

1 file changed

+267
-0
lines changed

1 file changed

+267
-0
lines changed

‎doc/proposals/ansible-helm-addapi.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
---
2+
title: Ansible/Helm add api command proposal for Operator SDK
3+
authors:
4+
- "@bharathi-tenneti"
5+
reviewers:
6+
- "@fabianvf"
7+
- "@cmacedo"
8+
approvers:
9+
- "@fabianvf"
10+
- "@jlanford"
11+
- "@dmesser"
12+
creation-date: 2020-03-10
13+
last-updated: 2020-03-15
14+
status: implementable
15+
---
16+
17+
18+
# Ansible/Helm add API command proposal for Operator SDK
19+
20+
21+
## Release Signoff Checklist
22+
23+
- \[x\] Enhancement is `implementable`
24+
- \[x\] Design details are appropriately documented from clear requirements
25+
- \[ \] Test plan is defined
26+
- \[ \] Accceptance criteria
27+
- \[ \] User-facing documentation is created
28+
29+
30+
31+
## Summary
32+
33+
The proposal is to enable Ansible/Helm operator developers to create additional APIs, through SDK CLI.
34+
35+
## Motivation
36+
37+
As of today, SDK CLI can be used only to add additonal APIs for Go based Operators.
38+
Ansible/Helm operator developers are not able to create additonal APIs via CLI, once the original project scaffolds. Today, developers have to manually add necessary files to the project scaffold.
39+
40+
## Goals
41+
42+
* Ansible/Helm operator developer can use existing SDK CLI commands to create additonal APIs as needed.
43+
* Ansible/Helm operator developer should be able to use flags necessary for Ansible/Helm as used in `operator-sdk new`CLI. for adding additional APIs as well.
44+
* Ansible/Helm operator developer can find supported documentation for the same.
45+
46+
## Non-Goals
47+
48+
* Updating Molecule tests for additional APIs created for Anible based operators.<**TBD**>
49+
* Generating/Updating Playbook for additional APIs for Ansible based operators. <**TBD**>
50+
51+
## Proposal
52+
53+
### User Stories
54+
55+
#### Story 1 - Ansible operator additional API
56+
As an Ansible operator developer, I would like to scaffold additional API, once the original Ansible operator project has been created. Goal is to use following command, to create additonal APIs.
57+
`operator-sdk add api --kind <kind> --api-version <group/version> [flags]`
58+
59+
##### Acceptance Criteria
60+
61+
* Ansible operator developer should be able to scaffold all resources needed for the additional API with following command.
62+
`operator-sdk add api --kind <kind> --api-version <group/version> [flags]`
63+
* Flags options available for `operator-sdk new`, should also be made available for `operator-sdk add api`, as shown below.
64+
```
65+
--api-version string - CRD APIVersion in the format $GROUP_NAME/$VERSION (e.g app.example.com/v1alpha1)
66+
--kind string - CRD Kind. (e.g AppService)
67+
--generate-playbook - Generate a playbook skeleton. (Only used for --type ansible) [**TBD**]
68+
```
69+
* Documentation for [SDK CLI reference][sdkclidoc] is updated with steps to add additonal APIs for Ansible based operator.
70+
* Documentation is updated for [operator-sdk add api][addapidoc] for ansible.
71+
72+
73+
#### Story 2 - Helm operator additional API
74+
75+
As Helm operator developer, I would like to scaffold additional API, once the original Helm operator project has been created, using following command.
76+
`operator-sdk add api --kind <kind> --api-version <group/version> [flags]`
77+
78+
##### Acceptance Criteria
79+
* Helm operator developer should be able to scaffold all resources needed for the additional API with any of below commands,
80+
`operator-sdk add api --kind <kind> --api-version <group/version> [flags]`
81+
* Flags options available for `operator-sdk new`, should also be made available for `operator-sdk add api`
82+
```
83+
--api-version string - CRD APIVersion in the format $GROUP_NAME/$VERSION (e.g app.example.com/v1alpha1)
84+
--kind string - CRD Kind. (e.g AppService)
85+
--helm-chart string - Initialize helm operator with existing helm chart (<URL>, <repo>/<name>, or local path)
86+
--helm-chart-repo string - Chart repository URL for the requested helm chart
87+
--helm-chart-version string - Specific version of the helm chart (default is latest version)
88+
```
89+
* Documentation for [SDK CLI reference][sdkclidoc] is updated with steps to add additonal APIs for Helm based operator.
90+
* Documentation is updated for [operator-sdk add api][addapidoc] for helm.
91+
92+
93+
94+
### Implementation Details/Notes/Constraints
95+
96+
* The `operator-sdk new memcached-operator --api-version=cache.example.com/v1alpha1 --kind=Memcached --type=ansible` command scaffolds new ansible based operator for the user with given API.Please refer below logic being used to determine the type of operator:
97+
```go
98+
case projutil.OperatorTypeAnsible:
99+
if err := doAnsibleScaffold(); err != nil {
100+
return err
101+
}
102+
case projutil.OperatorTypeHelm:
103+
if err := doHelmScaffold(); err != nil {
104+
return err
105+
}
106+
```
107+
and subsequently [`func doAnsibleScaffold()`][doansible] or [`func doHelmScaffold()`][dohelm] is being called to perform the scaffold.
108+
109+
Currently, `operator-sdk add api` only allows Go-based operators to create further APIs, after the original project is scaffolded. By posing restriction as shown [here][onlygorestriction].
110+
```go
111+
// Only Go projects can add apis.
112+
if err := projutil.CheckGoProjectCmd(cmd); err != nil {
113+
return err
114+
}
115+
```
116+
* This proposal is to enhance [`func apiRun(cmd *cobra.Command, args []string)`][addapifunc] to add APIs for Ansible/Helm operators, by re-using pre-existing functions as shown above to check for `--type`, and perform necessary scaffolds for the new resource.
117+
118+
* To this extent, PoCs have been done for both [Ansible][ansiblepoc] and [Helm][helmpoc] by manually adding necessary files in the scaffold. Please see below for project layout.
119+
**NOTE**: To test/check the POCs locally used the makefile targets `make install` and `make uninstall`.
120+
121+
* Ansible roles scaffold after adding APIs:
122+
```
123+
── roles
124+
│   ├── memcached
125+
│   │   ├── README.md
126+
│   │   ├── defaults
127+
│   │   │   └── main.yml
128+
│   │   ├── files
129+
│   │   ├── handlers
130+
│   │   │   └── main.yml
131+
│   │   ├── meta
132+
│   │   │   └── main.yml
133+
│   │   ├── tasks
134+
│   │   │   └── main.yml
135+
│   │   ├── templates
136+
│   │   └── vars
137+
│   │   └── main.yml
138+
│   ├── myapp
139+
│   │   ├── README.md
140+
│   │   ├── defaults
141+
│   │   │   └── main.yml
142+
│   │   ├── files
143+
│   │   ├── handlers
144+
│   │   │   └── main.yml
145+
│   │   ├── meta
146+
│   │   │   └── main.yml
147+
│   │   ├── tasks
148+
│   │   │   └── main.yml
149+
│   │   ├── templates
150+
│   │   └── vars
151+
│   │   └── main.yml
152+
```
153+
154+
* Helm charts are scaffolded as shown below for new APIs:
155+
```bash
156+
├── helm-charts
157+
│   ├── memcached
158+
│   │   ├── Chart.yaml
159+
│   │   ├── README.md
160+
│   │   ├── templates
161+
│   │   │   ├── NOTES.txt
162+
│   │   │   ├── _helpers.tpl
163+
│   │   │   ├── pdb.yaml
164+
│   │   │   ├── statefulset.yaml
165+
│   │   │   └── svc.yaml
166+
│   │   └── values.yaml
167+
│   ├── mongodb
168+
│   │   ├── Chart.yaml
169+
│   │   ├── OWNERS
170+
│   │   ├── README.md
171+
│   │   ├── files
172+
│   │   │   └── docker-entrypoint-initdb.d
173+
│   │   │   └── README.md
174+
│   │   ├── templates
175+
│   │   │   ├── NOTES.txt
176+
│   │   │   ├── _helpers.tpl
177+
│   │   │   ├── configmap.yaml
178+
│   │   │   ├── deployment-standalone.yaml
179+
│   │   │   ├── ingress.yaml
180+
│   │   │   ├── initialization-configmap.yaml
181+
│   │   │   ├── poddisruptionbudget-arbiter-rs.yaml
182+
│   │   │   ├── poddisruptionbudget-secondary-rs.yaml
183+
│   │   │   ├── prometheus-alerting-rule.yaml
184+
│   │   │   ├── prometheus-service-monitor.yaml
185+
│   │   │   ├── pvc-standalone.yaml
186+
│   │   │   ├── secrets.yaml
187+
│   │   │   ├── statefulset-arbiter-rs.yaml
188+
│   │   │   ├── statefulset-primary-rs.yaml
189+
│   │   │   ├── statefulset-secondary-rs.yaml
190+
│   │   │   ├── svc-headless-rs.yaml
191+
│   │   │   ├── svc-primary-rs.yaml
192+
│   │   │   └── svc-standalone.yaml
193+
│   │   ├── values-production.yaml
194+
│   │   ├── values.schema.json
195+
│   │   └── values.yaml
196+
│   └── nginx
197+
│   ├── Chart.yaml
198+
│   ├── charts
199+
│   ├── templates
200+
│   │   ├── NOTES.txt
201+
│   │   ├── _helpers.tpl
202+
│   │   ├── deployment.yaml
203+
│   │   ├── ingress.yaml
204+
│   │   ├── service.yaml
205+
│   │   ├── serviceaccount.yaml
206+
│   │   └── tests
207+
│   │   └── test-connection.yaml
208+
│   └── values.yaml
209+
```
210+
* Along with above changes,`/deploy/role.yaml` will be updated to reflect new apiGroups.
211+
``` yaml
212+
- apiGroups:
213+
- cache.example.com
214+
resources:
215+
- '*'
216+
verbs:
217+
- create
218+
- delete
219+
- get
220+
- list
221+
- patch
222+
- update
223+
- watch
224+
- apiGroups:
225+
- app.example.com
226+
resources:
227+
- '*'
228+
verbs:
229+
- create
230+
- delete
231+
- get
232+
- list
233+
- patch
234+
- update
235+
- watch
236+
```
237+
* CRD and CR files will be generated at `/deploy/crds`, as shown below.
238+
```
239+
── deploy
240+
│   ├── crds
241+
│   │   ├── cache.example.com_memcacheds_crd.yaml
242+
│   │   ├── cache.example.com_v1alpha1_memcached_cr.yaml
243+
│   │   ├── charts.helm.k8s.io_mongodbs_crd.yaml
244+
│   │   ├── charts.helm.k8s.io_v1alpha1_mongodb_cr.yaml
245+
│   │   ├── example.com_nginxes_crd.yaml
246+
│   │   └── example.com_v1alpha1_nginx_cr.yaml
247+
```
248+
* watches.yaml at `/watches.yaml` gets updated with new API resource as shown below.
249+
```yaml
250+
- version: v1alpha1
251+
group: cache.example.com
252+
kind: Memcached
253+
role: /opt/ansible/roles/memcached
254+
255+
- version: v1alpha1
256+
group: cache.example.com
257+
kind: Mykind
258+
role: /opt/ansible/roles/mykind
259+
```
260+
[addapidoc]:https://github.com/operator-framework/operator-sdk/blob/master/doc/cli/operator-sdk_add_api.md
261+
[sdkclidoc]:https://github.com/operator-framework/operator-sdk/blob/master/doc/sdk-cli-reference.md
262+
[onlygorestriction]:https://github.com/operator-framework/operator-sdk/blob/master/cmd/operator-sdk/add/api.go#L95
263+
[doansible]:https://github.com/operator-framework/operator-sdk/blob/master/cmd/operator-sdk/new/cmd.go#L228
264+
[dohelm]:https://github.com/operator-framework/operator-sdk/blob/master/cmd/operator-sdk/new/cmd.go#L320
265+
[addapifunc]:https://github.com/operator-framework/operator-sdk/blob/master/cmd/operator-sdk/add/api.go#L91
266+
[ansiblepoc]:https://github.com/bharathi-tenneti/memcached-ansible-demo
267+
[helmpoc]:https://github.com/bharathi-tenneti/helm-operator-demo

0 commit comments

Comments
 (0)