piraeus-operator icon indicating copy to clipboard operation
piraeus-operator copied to clipboard
verified publisher icon piraeusdatastore

[v2]: Documentation

Open WanzenBug opened this issue 3 years ago • 2 comments

Now that Operator v2 is in a usable state, we need to have guides ready so users can actually use it. Currently, the documentation is split between CRD schema and description and README. We should provide proper documentation for all needs.

We should keep in mind the "four kinds of documentation". As reference nomad seems to have some nice docs.

Comparing to Operator v1, we had:

  • a bit of reference documentation for the helm values
  • a long how-to/tutorial for the install process, with jumping of points to configure various components
  • almost no explanation

We should rework this. My current idea:

  • [x] Tutorials:
    • [x] "Installing" in README
    • [x] Create a volume
    • [x] Failover stateful workload
    • [x] Create a snapshot
  • [ ] How-To-Guides
    • [ ] Production environment
    • [ ] S3 Snapshots
  • [ ] Explanation
    • [ ] Architecture
    • [ ] LINSTOR/DRBD intro
    • [ ] LINSTOR CRDs
    • [ ] Fail-Over with HA Controller
    • [x] DRBD loader selection
  • [x] Reference
    • [x] CRD options
      • [x] #369
      • [x] #371
      • [x] #372
    • [x] DRBD loader image config

WanzenBug avatar Dec 12 '22 15:12 WanzenBug

Great work with v2 Operator ;)

Please add also "Uninstall" section. I was experimenting with various settings. I created and deleted LinstorCluster, created it again and deleted it again and now there are many CRDs left that I am not sure if I can delete or not, to be able to start with the clean setup again.

kubectl get linstorcluster
No resources found

kubectl get crds | grep -o ".*.internal.linstor.linbit.com" | xargs -i{} sh -c "kubectl get {} -ojson|jq '.items[]|{kind:.kind, name:.metadata.name}'"
{ "kind": "LayerDrbdResourceDefinitions", "name": "706289e692742c4f9b1a212584444be9ca3985b9692927a3570b8abed91abec7" }
{ "kind": "LayerDrbdResources", "name": "4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a" }
...
{ "kind": "LayerDrbdResources", "name": "d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35" }
{ "kind": "LayerResourceIds", "name": "0b918943df0962bc7a1824c0555a389347b4febdc7cf9d1254406d80ce44e3f9" }
...
{ "kind": "LayerResourceIds", "name": "ef2d127de37b942baad06145e54b0c619a1f22327b2ebbcfbec78f5564afe39d" }
{ "kind": "LinstorVersion", "name": "version" }
{ "kind": "NodeNetInterfaces", "name": "6bcd85595c4ed1bc4bb682632a80280087590275430f65ec529ba9ca9e22f17f" }
...
{ "kind": "NodeNetInterfaces", "name": "e6d2c783f0a20c68b0aae0e90ce0271814cc4e8ca6cbef7c37e3fbce762876f6" }
{ "kind": "Nodes", "name": "21d44fbd10de1a480954fd8a3b3cfc8bf794125b6a587f2d7680f1ae272b4934" }
...
{ "kind": "Nodes", "name": "f20544997e3ef0172dbb0e79450e82e1329f115842e555bf115d07f18d2daf8f" }
{ "kind": "NodeStorPool", "name": "08398c1e5bd13a711fbb009007989a3ff5873487f9262de06e0607b4810eb747" }
...
{ "kind": "NodeStorPool", "name": "fec092091e24239cec74a03d11c80037ff0664f05abf096f97525fbd260204f7" }
{ "kind": "PropsContainers", "name": "013481318b464d65bae5b16efb72a65a3f1020ea7a3d46a5f5a1690fa8ef8b5d" }
...
{ "kind": "PropsContainers", "name": "fddbef4a64883de21d1d5ae87b03485f60272005fa028d5cd02eab69f3518d9f" }
{ "kind": "ResourceDefinitions", "name": "9da917765d1321786016b3a5d2260e2b2d7284d388a06604ec3abe65503d51f3" }
{ "kind": "ResourceGroups", "name": "afaa583ea4fa8cb7153d514ab85561e01201aae9a93c60bced221e8305576e42" }
{ "kind": "ResourceGroups", "name": "fa9caf795d18b93f6b418ffee6b6bd6e36536e0af0c70d3e47aca3f5e989540c" }
{ "kind": "Resources", "name": "190967a09cdca97fa68bbd1e7190b7d894c5018eda087f7f1b5b85b8ec269392" }
...
{ "kind": "Resources", "name": "a64daa4fc9727a602c747060a8d732743d11d1a79d4533363557bed44e9f8fc0" }
{ "kind": "SecAccessTypes", "name": "28baebc3d12621e39673279d6837b21441f1b563cd5b9ceee9a46a8215be5538" }
...
{ "kind": "SecAccessTypes", "name": "b3c2ed23b44e753d6bfc54b1d48ff7d0e4959624ecf1ceb1d0942bac08548634" }
{ "kind": "SecAclMap", "name": "062b5d531d1d5423af1e7bc42c3b13409e2f3a5fa907e444d8b74554dba075ea" }
...
{ "kind": "SecAclMap", "name": "f5bf2c31c0b463ff2174f9521d5286f1bd7aae2ad89aaea960ac18f089df4107" }
{ "kind": "SecConfiguration", "name": "16d322f7606586323d97ce609b0e0ccd53921319395f779f5394c588b3537b84" }
{ "kind": "SecConfiguration", "name": "dba41c42c9e7ed5153467a4c700c1029d538d90b81628c41c11589de8efee734" }
{ "kind": "SecDfltRoles", "name": "d621c1a7169f2ca51bc8674da52e9572178a66a1dde88da24da78fe4951703f9" }
{ "kind": "SecDfltRoles", "name": "d9262e7fb868c502061473089e5212378ac3935e2f96294266da6d7eec7d44e0" }
{ "kind": "SecIdentities", "name": "d621c1a7169f2ca51bc8674da52e9572178a66a1dde88da24da78fe4951703f9" }
{ "kind": "SecIdentities", "name": "d9262e7fb868c502061473089e5212378ac3935e2f96294266da6d7eec7d44e0" }
{ "kind": "SecIdRoleMap", "name": "d45c0fcd05bfa6eeb06774806da3bdd85df1f837d9e81f1065d1acd6419e2c78" }
{ "kind": "SecIdRoleMap", "name": "e242db1bf68757cc159ba45d43c7dec786531c47f0d893f2047c0b8453e294ef" }
{ "kind": "SecObjectProtection", "name": "01e59f111c26effc681478b3309ee35eef3c8152ed929cbd5bc0e459966a571e" }
...
{ "kind": "SecObjectProtection", "name": "fb7387028dcd930efbceb8bcdfa1f40dfc623c29f6bf18bee3a4563c9d77deab" }
{ "kind": "SecRoles", "name": "92b7b421992ef490f3b75898ec0e511f1a5c02422819d89719b20362b023ee4f" }
...
{ "kind": "SecRoles", "name": "dc6190c8b399e043b9dfbacbb0d37f2a2645e33f9938491d24b24e0298d9cd17" }
{ "kind": "SecTypeRules", "name": "0f5443147fb6c7c0c50298f2af1d388c5d241e89e2287979d012c6c9396e31fb" }
...
{ "kind": "SecTypeRules", "name": "f82532cbed710629253dca93cf66f6e7aee0f4fff93b6e95bae795811f858126" }
{ "kind": "SecTypes", "name": "0e1d1edc14ed3bf8189fba45c65a3775f9add9f5cffb0ea795bcb2c8f7ad4348" }
...
{ "kind": "SecTypes", "name": "dc6190c8b399e043b9dfbacbb0d37f2a2645e33f9938491d24b24e0298d9cd17" }
{ "kind": "SpaceHistory", "name": "019cca034bc7fd1e42be693f532f82505f3ec798a470055d610817428d50a017" }
...
{ "kind": "SpaceHistory", "name": "fce2d8b8e0969a325bfed2e2aa8d3964deb3f57319c27df6bbe7bcad513a173f" }
{ "kind": "StorPoolDefinitions", "name": "018f289155b47416679dd18d9bfafad480b139a93a643f79c2e305bc6f5618b0" }
{ "kind": "StorPoolDefinitions", "name": "c2b5778ccd555d92172a6e89e33594f34421b7fe8034c612123bf3d0c4f9697f" }
{ "kind": "TrackingDate", "name": "current" }
{ "kind": "VolumeGroups", "name": "96eb55511ba1f24ae262fe3b13cbe55a7787a482b15c424bc817e16e148e9e28" }

RichardSufliarsky avatar Mar 22 '23 19:03 RichardSufliarsky

I realized how to start with clean config (steps 1, 4 maybe not needed).

  1. scale down operator kubectl scale -n piraeus-datastore deployment piraeus-operator-controller-manager --replicas=0
  2. back up linstor CRDs
kubectl get crds | grep -o ".*.internal.linstor.linbit.com" | xargs kubectl get crds -oyaml > crds.yaml
kubectl get crds | grep -o ".*.internal.linstor.linbit.com" | xargs -i{} sh -c "kubectl get {} -oyaml > {}.yaml"
  1. delete linstor CRDs kubectl get crds | grep -o ".*.internal.linstor.linbit.com" | xargs --no-run-if-empty kubectl delete crds
  2. scale up operator kubectl scale -n piraeus-datastore deployment piraeus-operator-controller-manager --replicas=1

Then created LinstorCluster again and it is working :)

RichardSufliarsky avatar Mar 22 '23 21:03 RichardSufliarsky