1
2# Device Registrar Service Guide
3
4To view the device registrar APIs, please visit the [NCR Edge Wiki](https://wiki.edge-infra.dev/edge/components/device-registrar/api/)
5
6## Local Dev setup
7
8Start the server on kind cluster
9```bash
10# start a fresh kind cluster
11just hack/kind/reset
12# deploy cert manager
13just cmd/edge/device-registrar/cert-manager
14# deploy EdgeID
15just cmd/edge/iam/kind
16# deploy device-registrar service
17just cmd/edge/device-registrar/kind
18```
19Then the service will be available at localhost:8080
20
21
22## Flows
23### Pre-reqs
241. Create an externalApplication CR on the cluster. The CRD definition can be found [here](../../../config/pallets/edge/device-registrar/base/crds/device-registrar.edge.ncr.com_externalapplications.yaml).
25Below is an example:
26```yaml
27apiVersion: device-registrar.edge.ncr.com/v1alpha1
28kind: ExternalApplication
29metadata:
30 name: connected-associates
31 namespace: device-registrar-clients # the CR must be created in this namespace
32spec:
33 ID: "123e4567-e89b-12d3-a456-426614174000"
34 description: "Connected associates mobile application definition"
35 clientTemplate:
36 apiVersion: iam.edge-infra.dev/v1alpha1
37 kind: Client
38 metadata:
39 name: connected-associates-client
40 labels:
41 app: example
42 annotations:
43 description: "Example client for demonstration purposes"
44 spec:
45 audience:
46 - "example-audience"
47 clientName: "Connected Associates"
48 grantTypes:
49 - "authorization_code"
50 printBarcodeTypes:
51 - "QR"
52 printBarcodeUri: "https://example.com/print-barcode"
53 redirectUris:
54 - "https://example.com/callback"
55 responseModes:
56 - "query"
57 responseTypes:
58 - "code"
59 roles:
60 - "user"
61 scope: "openid profile email"
62 secretName: "example-client-secret"
63```
642. Configure discovery endpoint for the workload:
65Include an discovery CR as part of the workload helm chart.
66```yaml
67apiVersion: device-registrar.edge.ncr.com/v1alpha1
68kind: Discovery
69metadata:
70 name: javis-config-discovery
71 namespace: jarvis-namespace
72spec:
73 name: jarvis # well-known service name
74 url: https://jarvis.store.ncr.corp/config
75```
76
77### Simplified bootstrap flow
78
79
80#### To start a pairing process:
81Locally
82```bash
83curl -X POST http://localhost:8080/pair
84```
85In store
86```bash
87curl -X POST http://device-registrar-svc.device-registrar/pair
88```
89which returns:
90```bash
91{"connectURL":"https://edge-bootstrap.store.ncr.corp/connect/D46EX2C6HBGSLXG","hostMapping":{"host":"edge-bootstrap.store.ncr.corp","vip":"10.10.11.2"}}
92```
93
94#### To connect a device:
95Locally
96```bash
97# '{
98# "device": {
99# "name": "test-device-name", # required
100# "description": "my test device", # optional
101# "serialNumber": "DSFE7DSCXX90" # required
102# },
103# "applicationIDs": ["123e4567-e89b-12d3-a456-426614174000"] # required
104# }'
105curl -X POST http://localhost:8080/connect/D46EX2C6HBGSLXG -H "Content-Type: application/json" -d '{
106 "device": {
107 "name": "test-device-name",
108 "description": "my test device",
109 "serialNumber": "DSFE7DSCXX90"
110 },
111 "applicationIDs": ["123e4567-e89b-12d3-a456-426614174000"]
112}'
113```
114In store
115```bash
116# '{
117# "device": {
118# "name": "test-device-name", # required
119# "description": "my test device", # optional
120# "serialNumber": "DSFE7DSCXX90" # optional
121# },
122# "applicationIDs": ["123e4567-e89b-12d3-a456-426614174000"] # required
123# }'
124# run `kubectl get secret -n emissary emissary-ca -o jsonpath='{.data.ca\.crt}' | base64 -d` to extract the ca cert
125# save output to ca.cert.pem
126curl --cacert ca.cert.pem -X POST https://edge-bootstrap.store.ncr.corp/connect/D46EX2C6HBGSLXG -H "Content-Type: application/json" -d '{
127 "device": {
128 "name": "test-device-name",
129 "description": "my test device",
130 "serialNumber": "DSFE7DSCXX90"
131 },
132 "applicationIDs": ["123e4567-e89b-12d3-a456-426614174000"]
133}'
134```
135which returns:
136```bash
137{"applications":[{"id":"123e4567-e89b-12d3-a456-426614174000","name":"connected-associates","config":{"clientID":"7903dbf3-defb-448e-a457-c3217642523b","clientSecret":"fH4FeMcZhRjFDbePkiKWiCR7ER"}}],"deviceAuth":{"tls.crt":"REDACTED","tls.key":"REDACTED"},"hostMapping":{"host":"store.ncr.corp","vip":"10.10.11.2"}}
138```
139
140### Old bootstrap flow
141
142#### To list External Applications:
143Locally
144```bash
145curl -X GET http://localhost:8080/applications
146```
147In store
148```bash
149curl -X GET http://device-registrar-svc.device-registrar/applications
150```
151which returns:
152```bash
153[{"id":"123e4567-e89b-12d3-a456-426614174000","name":"connected-associates","description":"Connected associates mobile application definition"}]
154```
155
156and you can also see the CRD:
157```bash
158kubectl get extapp -A
159NAMESPACE NAME ID DESCRIPTION AGE
160device-registrar-clients connected-associates 123e4567-e89b-12d3-a456-426614174000 Connected associates mobile application definition 39s
161```
162
163
164#### To register a device:
165Locally
166```bash
167curl -X POST http://localhost:8080/register -H "Content-Type: application/application/json" -d '{
168 "device": {
169 "name": "test-device-name-old",
170 "description": "my test device",
171 "serialNumber": "DSFE7DSCXX90"
172 },
173 "applicationIDs": ["123e4567-e89b-12d3-a456-426614174000"]
174}'
175```
176In store
177```bash
178curl -X POST http://device-registrar-svc.device-registrar/register -H "Content-Type: application/application/json" -d '{
179 "device": {
180 "name": "test-device-name-old",
181 "description": "my test device",
182 "serialNumber": "DSFE7DSCXX90"
183 },
184 "applicationIDs": ["123e4567-e89b-12d3-a456-426614174000"]
185}'
186```
187which returns:
188```bash
189{"bootstrapURL":"https://edge-bootstrap.store.ncr.corp/bootstrap/F7RAXZXBFZQRPAU","hostMapping":{"host":"edge-bootstrap.store.ncr.corp","vip":"10.10.11.2"}}
190```
191
192#### To bootstrap a device:
193Locally
194```bash
195curl -X GET http://localhost:8080/bootstrap/F7RAXZXBFZQRPAU
196```
197In store
198```bash
199# run `kubectl get secret -n emissary emissary-ca -o jsonpath='{.data.ca\.crt}' | base64 -d` to extract the ca cert
200# save output to ca.cert.pem
201curl --cacert ca.cert.pem -X GET https://edge-bootstrap.store.ncr.corp/bootstrap/F7RAXZXBFZQRPAU
202```
203which returns:
204```bash
205{"applications":[{"id":"123e4567-e89b-12d3-a456-426614174000","name":"connected-associates","config":{"clientID":"e00a1c4b-2bdc-450b-8fc6-9b10cce3869f","clientSecret":"bnTV~gAZj.CkkyXVUpND~ks4wE"}}],"deviceAuth":{"tls.crt":"REDACTED","tls.key":"REDACTED"},"hostMapping":{"host":"store.ncr.corp","vip":"10.10.11.2"}}
206```
207
208### Service discovery
209#### To discover configuration endpoint for a service:
210Locally
211```bash
212curl -X GET "http://localhost:8080/discover/jarvis" \
213 -H "X-Client-DN: OU=urn:storeID:my-store-id+OU=urn:deviceName:my-test-device+OU=urn:SN:DSFE7DSCXX90"
214```
215In store
216```bash
217# run `kubectl get secret -n emissary emissary-ca -o jsonpath='{.data.ca\.crt}' | base64 -d` to extract the ca cert
218# save output to ca.cert.pem
219# use deviceAuth."tls.crt" from /connect API response
220# save output to tls.cert
221# use deviceAuth."tls.key" from /connect API response
222# save output to tls.key
223curl --cert tls.crt --key tls.key --cacert ca.cert.pem -X GET "https://edge.store.ncr.corp/discover/jarvis"
224```
225which returns:
226```bash
227{"name":"jarvis","url":"https://jarvis.store.ncr.corp/config"}
228```
229The API will look for the well-known service name in the request path e.g. jarvis. If the corresponding discovery CR is not found, the API will return
230```bash
231{"name":"jarvis","url":null}
232```
233
234### Additional APIs
235
236#### Delete External Application
237
238Locally:
239```
240curl -X DELETE http://localhost:8080/applications/[external-application-id]
241```
242
243In store:
244```
245curl -X DELETE http://device-registrar-svc.device-registrar/applications/[external-application-id]
246```
247which returns a `204` upon successful deletion.
248
249Example:
250```
251curl -v -X DELETE http://localhost:8080/applications/123e4567-e89b-12d3-a456-426614174000
252```
253
254#### To Delete External Device
255Locally
256```bash
257curl -X DELETE http://localhost:8080/devices/test-device-name
258```
259In store
260```bash
261curl -X DELETE http://device-registrar-svc.device-registrar/devices/test-device-name
262```
263
264## CRDs
265### To see all crds:
266```bash
267kubectl api-resources --api-group=device-registrar.edge.ncr.com
268NAME SHORTNAMES APIVERSION NAMESPACED KIND
269devicebindings devb device-registrar.edge.ncr.com/v1alpha1 true DeviceBinding
270discoveries device-registrar.edge.ncr.com/v1alpha1 true Discovery
271externalapplications extapp device-registrar.edge.ncr.com/v1alpha1 true ExternalApplication
272externaldevices extdev device-registrar.edge.ncr.com/v1alpha1 true ExternalDevice
273```
274
275## Generating Swagger UI Docs
276### To view the docs locally
277
278```
279just cmd/edge/device-registrar/docs
280```
281
282### To generate docs:
283```
284just cmd/edge/device-registrar/gen-docs
285```View as plain text