docs(orc8r): Added docs for simple gateway registration #12263
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,95 @@ | ||||||
| --- | ||||||
| id: dev_gateway_registration | ||||||
| title: Gateway Registration | ||||||
| hide_title: true | ||||||
| --- | ||||||
| # Gateway Registration | ||||||
|
|
||||||
| ## Motivation | ||||||
|
|
||||||
| Previously, to register a gateway, the operator would have to gather the gateway information (both the hardware ID and the challenge key) through `show_gateway_info.py` script, then provision the gateway with the correct values of `control_proxy.yml` and `rootCA.pem`. | ||||||
| Then, the operator would have to register each gateway through the NMS UI and validate the gateway registration by running `checkin_cli.py`. | ||||||
|
|
||||||
| In efforts to simplify gateway registration, the new registration process only requires two steps: registering the gateway at Orc8r and then running `register.py` at the gateway. | ||||||
|
|
||||||
| ## Overview | ||||||
|
|
||||||
| The overview of gateway registration is as follows: | ||||||
|  | ||||||
Neudrino marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| Note: The operator should set per-tenant default `control_proxy.yml` through the API endpoint `\tenants\{tenant_id}\control_proxy` as a prerequisite. | ||||||
| The control proxy must have `\n` characters as line breaks. Here is a sample request body: | ||||||
|
|
||||||
| ```json | ||||||
| { | ||||||
| "control_proxy": "nghttpx_config_location: /var/tmp/nghttpx.conf\n\nrootca_cert: /var/opt/magma/certs/rootCA.pem\ngateway_cert: /var/opt/magma/certs/gateway.crt\ngateway_key: /var/opt/magma/certs/gateway.key\nlocal_port: 8443\ncloud_address: controller.magma.test\ncloud_port: 7443\n\nbootstrap_address: bootstrapper-controller.magma.test\nbootstrap_port: 7444\nproxy_cloud_connections: True\nallow_http_proxy: True" | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| 1. The operator registers a gateway partially (i.e., without its device field) through Orc8r through an API call. It will receive a registration token, the `rootCA.pem`, and its Orc8r's domain name in the response body under the field registration info. For example, | ||||||
|
|
||||||
| ```json | ||||||
| { | ||||||
| "registration_info": { | ||||||
| "domain_name": "magma.test", | ||||||
| "registration_token": "reg_h9h2fhfUVuS9jZ8uVbhV3vC5AWX39I", | ||||||
| "root_ca": "-----BEGIN CERTIFICATE-----\nMIIDNTCCAh2gAwIBAgIUAX6gmuNG3v/vv7uZjL5sUKYflJ0wDQYJKoZIhvcNAQEL\nBQAwKTELMAkGA1UEBhMCVVMxGjAYBgNVBAMMEXJvb3RjYS5tYWdtYS50ZXN0MCAX\nDTIxMTAwMTIwMzYyOVoYDzMwMjEwMjAxMjAzNjI5WjApMQswCQYDVQQGEwJVUzEa\nMBgGA1UEAwwRcm9vdGNhLm1hZ21hLnRlc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IB\nDwAwggEKAoIBAQDN6k/+7buO/KwgJgRjE/LM5wmNvMWpxDfKJpdpUH6DrjQkEpZB\n8E8Ts9qwR6RSTh8H/jL/qkoHpTbIdHZhOtayY/t/zreIClAytWyJSaJfGoRfXzsV\nyzjD7Bk79YrgAja9cAJcqy26gURQsB173opnlKTzMCfiirpY3gbiJEy74s0M6uII\njGvxx1uvXauFBO5mbbAPmxG4fFXTBGJMcxvHtdU8Vizf2YkZXqoXni0gJ0TJFK4O\nVeZe8EWuUXsD1iEbxz/H752I4yfQ2Djuj6emjRJlAeKnPsQWSsR4Qt3Po0R5YOmn\nEEsOmlfH6vOm3eiYrhxlIQ7uEFw760IDe0OLAgMBAAGjUzBRMB0GA1UdDgQWBBT6\nVQqTB+bVV7foz2xPo3sUfAqnhDAfBgNVHSMEGDAWgBT6VQqTB+bVV7foz2xPo3sU\nfAqnhDAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQASxJHc6JTk\n5iZJOBEXzl8iWqIO9K8z3y46Jtc9MA7DnYO5v6HvYE8WnFn/FRui/MLiOb1OAsVk\nJpNHRkJJMB1KxD5RkyfXTcIE+LSu/XUJQDc2F4RnZPYhPExK8tcmqHTDV78m+LHl\nswOIjhQVn9r6TncsfOhLs0YkqikHSJz1i4foJGFiOmM5R91KuOvwOG4qQ1Xw1J64\n7sHA4OElf/CIt0ul7xfAlzbLXOaPBb8z82dR5H28+3srGayPgauM9EGIHulm1J53\nM4uFtM9sA/X/EWMLF1T5ACDTjpD74yhxX98hFNlDuABacer/RN1UB/iTG7eMMhIO\nWLRlFB4QVm8w\n-----END CERTIFICATE-----\n" | ||||||
| } | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| The registration token expires every 30 minutes and automatically refreshes every time the operator fetches this unregistered gateway. | ||||||
| 2. The operator runs the `register.py` script at the gateway with the registration token and its Orc8r's domain name. | ||||||
|
|
||||||
| ```shell | ||||||
| MAGMA-VM [/home/vagrant]$ sudo /home/vagrant/build/python/bin/python3 ~/magma/orc8r/gateway/python/scripts/register.py [-h] [--ca-file CA_FILE] [--cloud-port CLOUD_PORT] [--no-control-proxy] DOMAIN_NAME REGISTRATION_TOKEN | ||||||
| ``` | ||||||
|
|
||||||
| The operator can optionally set the root CA file with the `--ca-file CA_FILE` flag or disable writing to the control proxy file with the `--no-control-proxy` flag. | ||||||
| `sudo` permission is necessary because the script needs write access to the file `/var/opt/magma/configs/control_proxy.yml` for configuring the gateway. | ||||||
| For example, in a testing environment with the `rootCA.pem` and `control_proxy.yml` configured, the operator could run | ||||||
|
|
||||||
| ```shell | ||||||
| MAGMA-VM [/home/vagrant]$ sudo /home/vagrant/build/python/bin/python3 ~/magma/orc8r/gateway/python/scripts/register.py magma.test reg_t5S4zjhD0tXRTmkYKQoN91FmWnQSK2 --cloud-port 7444 --no-control-proxy | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| ``` | ||||||
|
|
||||||
| Upon success, the script will print the gateway information that was registered and run `checkin_cli.py` automatically. Below is an example of the output of a successful register attempt. | ||||||
|
|
||||||
| ```shell | ||||||
christinewang5 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| > Registered gateway | ||||||
| Hardware ID | ||||||
| ----------- | ||||||
| id: "aabf4fb9-0933-4039-95a8-b87ae7144d71" | ||||||
|
|
||||||
| Challenge Key | ||||||
| ----------- | ||||||
| key_type: SOFTWARE_ECDSA_SHA256 | ||||||
| key: "MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEQrZVdmuZpvciEXdznTErWUelOcgdBwPKQfOZDL7Wkl8ALSBtKvJWDPyhS6rkW9/xJdgPD4QK3Jqc4Eox5NT6SVYYuHWLv7b28493rwFvuC2+YurmfYj+LZh9VBVTvlwk" | ||||||
|
|
||||||
| Control Proxy | ||||||
| ----------- | ||||||
| nghttpx_config_location: /var/tmp/nghttpx.conf | ||||||
|
|
||||||
| rootca_cert: /var/opt/magma/certs/rootCA.pem | ||||||
| gateway_cert: /var/opt/magma/certs/gateway.crt | ||||||
| gateway_key: /var/opt/magma/certs/gateway.key | ||||||
| local_port: 8443 | ||||||
| cloud_address: controller.magma.test | ||||||
| cloud_port: 7443 | ||||||
|
|
||||||
| bootstrap_address: bootstrapper-controller.magma.test | ||||||
| bootstrap_port: 7444 | ||||||
| proxy_cloud_connections: True | ||||||
| allow_http_proxy: True | ||||||
|
|
||||||
| > Waiting 60.0 seconds for next bootstrap | ||||||
|
|
||||||
| > Running checkin_cli | ||||||
| 1. -- Testing TCP connection to controller.magma.test:7443 -- | ||||||
| 2. -- Testing Certificate -- | ||||||
| 3. -- Testing SSL -- | ||||||
| 4. -- Creating direct cloud checkin -- | ||||||
| 5. -- Creating proxy cloud checkin -- | ||||||
|
|
||||||
| Success! | ||||||
| ``` | ||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| --- | ||
| id: dev_rest_api_auth | ||
| title: REST API Auth | ||
| hide_title: true | ||
| --- | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The graphics uploaded above seems incomplete. I.e. the lines touching the bottom of the graphics indicate to me, that there is more to come in the process. Could we add a "termination" there indicating that the registration process is finished?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah I was using https://sequencediagram.org/ to create the diagram, it seems to format all its sequence diagrams like so
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What do you think about using the
bottomparticipantskeyword in that tool to somehow work around that issue?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If you created the graphics from some text (similar to mermaid), than you would probably also want to add a hidden section with the respective code to the docs.
In Github this would probably be a
<!-- HMTL comment block -->, maybe Docusaurus has something similar?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If hidden parts are not possible, you might want to use a details block.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi @christinewang5 ,
according to this slack message DocuSaurus does support mermaid diagrams. (Also see the examples for Github and Docusaurus).
Could you at least post the code, used to generate the graphics here in the thread, for a later cleanup, please.