1# Scripts User Guide
2
3This README documents:
4* What update-crd.sh and update-generated-code.sh do
5* When and how to use them
6
7## update-generated-code.sh
8
9This is the script to update clientset/informers/listers and API deepcopy code using [code-generator](https://github.com/kubernetes/code-generator).
10
11Make sure to run this script after making changes to /client/apis/volumesnapshot/v1/types.go.
12
13Pre-requisites for running update-generated-code.sh:
14
15* GOPATH=~/go
16
17* Ensure external-snapshotter repository is at ~/go/src/github.com/kubernetes-csi/external-snapshotter
18
19* git clone https://github.com/kubernetes/code-generator.git under ~/go/src/k8s.io
20
21* git checkout to version v0.19.0
22```bash
23git checkout v0.19.0
24```
25
26* Ensure the path exist ${GOPATH}/src/k8s.io/code-generator/generate-groups.sh
27
28Run: ./hack/update-generated-code.sh from the client directory.
29
30Once you run the script, you will get an output as follows:
31```bash
32Generating deepcopy funcs
33Generating clientset for volumesnapshot:v1 at github.com/kubernetes-csi/external-snapshotter/client/v4/clientset
34Generating listers for volumesnapshot:v1 at github.com/kubernetes-csi/external-snapshotter/client/v4/listers
35Generating informers for volumesnapshot:v1 at github.com/kubernetes-csi/external-snapshotter/client/v4/informers
36
37```
38
39NOTE: We need to keep both v1beta1 and v1 snapshot clients at the current phase.
40
41## update-crd.sh
42
43NOTE: We need to serve both v1beta1 and v1 snapshot APIs and keep storage version at v1beta1 at the current phase.
44
45This is the script to update CRD yaml files under /client/config/crd/ based on types.go file.
46
47Make sure to run this script after making changes to /client/apis/volumesnapshot/v1/types.go.
48
49Follow these steps to update the CRD:
50
51* Run ./hack/update-crd.sh from client directory, new yaml files should have been created under ./config/crd/
52
53* Add api-approved.kubernetes.io annotation value in all yaml files in the metadata section with the PR where the API is approved by the API reviewers. The current approved PR for snapshot v1 API is https://github.com/kubernetes-csi/external-snapshotter/pull/419. Refer to https://github.com/kubernetes/enhancements/pull/1111 for details about this annotation.
54
55* Remove any metadata sections from the yaml file which does not belong to the generated type.
56For example, the following command will add a metadata section for a nested object, remove any newly added metadata sections. TODO(xiangqian): this is to make sure the generated CRD is compatible with apiextensions.k8s.io/v1. Once controller-gen supports generating CRD with apiextensions.k8s.io/v1, switch to use the correct version of controller-gen and remove the last step from this README.
57
58```bash
59./hack/update-crd.sh; git diff
60+ metadata:
61+ description: 'Standard object''s metadata. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#metadata'
62 type: object
63```
64
65* Update the restoreSize property to string in snapshot.storage.k8s.io_volumesnapshots.yaml
66
67The generated yaml file contains restoreSize property anyOf as described below:
68
69```bash
70 restoreSize:
71 anyOf:
72 - type: integer
73 - type: string
74 description: restoreSize represents the complete size of the snapshot
75 in bytes. In dynamic snapshot creation case, this field will be filled
76 in with the "size_bytes" value returned from CSI "CreateSnapshotRequest"
77 gRPC call. For a pre-existing snapshot, this field will be filled
78 with the "size_bytes" value returned from the CSI "ListSnapshots"
79 gRPC call if the driver supports it. When restoring a volume from
80 this snapshot, the size of the volume MUST NOT be smaller than the
81 restoreSize if it is specified, otherwise the restoration will fail.
82 If not specified, it indicates that the size is unknown.
83```
84
85Update the restoreSize property to use type string only:
86
87```bash
88
89 restoreSize:
90 type: string
91 description: restoreSize represents the complete size of the snapshot
92 in bytes. In dynamic snapshot creation case, this field will be filled
93 in with the "size_bytes" value returned from CSI "CreateSnapshotRequest"
94 gRPC call. For a pre-existing snapshot, this field will be filled
95 with the "size_bytes" value returned from the CSI "ListSnapshots"
96 gRPC call if the driver supports it. When restoring a volume from
97 this snapshot, the size of the volume MUST NOT be smaller than the
98 restoreSize if it is specified, otherwise the restoration will fail.
99 If not specified, it indicates that the size is unknown.
100
101```
102
103* In `client/config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml`, we need to add the `oneOf` constraint to make sure only one of `persistentVolumeClaimName` and `volumeSnapshotContentName` is specified in the `source` field of the `spec` of `VolumeSnapshot`.
104
105```
106 source:
107 description: source specifies where a snapshot will be created from. This field is immutable after creation. Required.
108 properties:
109 persistentVolumeClaimName:
110 description: persistentVolumeClaimName specifies the name of the PersistentVolumeClaim object representing the volume from which a snapshot should be created. This PVC is assumed to be in the same namespace as the VolumeSnapshot object. This field should be set if the snapshot does not exists, and should be created. This field is immutable.
111 type: string
112 volumeSnapshotContentName:
113 description: volumeSnapshotContentName specifies the name of a pre-existing VolumeSnapshotContent object representing an existing volume snapshot. This field should be set if the snapshot already exists. This field is immutable.
114 type: string
115 type: object
116 oneOf:
117 - required: ["persistentVolumeClaimName"]
118 - required: ["volumeSnapshotContentName"]
119 volumeSnapshotClassName:
120```
121
122* In `client/config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml `, we need to add the `oneOf` constraint to make sure only one of `snapshotHandle` and `volumeHandle` is specified in the `source` field of the `spec` of `VolumeSnapshotContent`.
123
124```
125 source:
126 description: source specifies from where a snapshot will be created. This field is immutable after creation. Required.
127 properties:
128 snapshotHandle:
129 description: snapshotHandle specifies the CSI "snapshot_id" of a pre-existing snapshot on the underlying storage system. This field is immutable.
130 type: string
131 volumeHandle:
132 description: volumeHandle specifies the CSI "volume_id" of the volume from which a snapshot should be dynamically taken from. This field is immutable.
133 type: string
134 type: object
135 oneOf:
136 - required: ["snapshotHandle"]
137 - required: ["volumeHandle"]
138 volumeSnapshotClassName:
139```
140
141* Because we need to serve both v1 and v1beta1 snapshot APIs, we need to make sure that both v1 and v1beta1 APIs are in the manifest yaml file. Because `update-crd.sh` only generates v1 manifest, make sure to copy the v1beta1 manifest below the v1 manifest after running `update-crd.sh` in the manifest yaml files. See `snapshot.storage.k8s.io_volumesnapshots.yaml` as an example. `served` is true for both v1beta1 and v1. `storage` is true for v1beta and false for v1.
142
143```
144spec:
145 group: snapshot.storage.k8s.io
146 names:
147 kind: VolumeSnapshot
148 listKind: VolumeSnapshotList
149 plural: volumesnapshots
150 singular: volumesnapshot
151 scope: Namespaced
152 versions:
153 - additionalPrinterColumns:
154 - description: Indicates if a snapshot is ready to be used to restore a volume.
155 jsonPath: .status.readyToUse
156 name: ReadyToUse
157 type: boolean
158......
159 - description: Timestamp when the point-in-time snapshot is taken by the underlying storage system.
160 jsonPath: .status.creationTime
161 name: CreationTime
162 type: date
163 - jsonPath: .metadata.creationTimestamp
164 name: Age
165 type: date
166 name: v1
167 schema:
168 openAPIV3Schema:
169 description: VolumeSnapshot is a user's request for either creating a point-in-time snapshot of a persistent volume, or binding to a pre-existing snapshot.
170 properties:
171......
172 served: true
173 storage: false
174 subresources:
175 status: {}
176 - additionalPrinterColumns:
177 - description: Indicates if a snapshot is ready to be used to restore a volume.
178 jsonPath: .status.readyToUse
179 name: ReadyToUse
180 type: boolean
181......
182 - description: Timestamp when the point-in-time snapshot is taken by the underlying storage system.
183 jsonPath: .status.creationTime
184 name: CreationTime
185 type: date
186 - jsonPath: .metadata.creationTimestamp
187 name: Age
188 type: date
189 name: v1beta1
190 schema:
191 openAPIV3Schema:
192 description: VolumeSnapshot is a user's request for either creating a point-in-time snapshot of a persistent volume, or binding to a pre-existing snapshot.
193 properties:
194......
195 served: true
196 storage: true
197 subresources:
198 status: {}
199status:
200 acceptedNames:
201 kind: ""
202 plural: ""
203 conditions: []
204 storedVersions: []
205``````
View as plain text