From ca99c971827c4f88534ce6ac55dc0237e131cceb Mon Sep 17 00:00:00 2001 From: Paul Marshall Date: Wed, 25 Mar 2026 15:57:49 -0500 Subject: [PATCH 1/3] Add docs for cc-login --- source/technical/cli/cc_login.rst | 59 +++++++++++++++++++++++++++++++ source/technical/cli/index.rst | 1 + 2 files changed, 60 insertions(+) create mode 100644 source/technical/cli/cc_login.rst diff --git a/source/technical/cli/cc_login.rst b/source/technical/cli/cc_login.rst new file mode 100644 index 0000000..d2ae710 --- /dev/null +++ b/source/technical/cli/cc_login.rst @@ -0,0 +1,59 @@ +.. _cli-cc-login: + +cc-login command +================ + +If you use a CC-* image, a ``cc-login`` command will be available in the +``cc`` user's `PATH`. The command performs device authentication, caches an +application credential for reuse, and can generate OpenStack ``openrc`` files +or entries for ``clouds.yaml`` so the OpenStack CLI and libraries can use the +cached credential. + +Usage +~~~~~ + +.. code-block:: console + + cc-login [OPTIONS] + +Options +~~~~~~~ + +The command accepts various options to configure authentication, credential caching, +and output format. Some of the most commonly used ones are: + +- ``--app-cred-name``, ``--app-cred-expires-hours``: Name and lifetime (in hours) + for the application credential (default: 24 hours). +- ``--ttl-seconds``: Local cache validity period in seconds before cc-login will + refresh the credential (default: 24 hours). +- ``--force-refresh``: Bypass the local cache and perform fresh device + authentication + app-credential creation. +- ``--output-openrc``, ``--force-openrc``: Write an ``openrc``-style file with + the app-credential (useful for sourcing in shell sessions). + Use ``--force-openrc`` to overwrite an existing file. +- ``--output-clouds-yaml``, ``--cloud-name``, ``--force-clouds-yaml``: + Add or update a cloud entry in ``clouds.yaml`` (default cloud name: ``chameleon``). + Use ``--force-clouds-yaml`` to overwrite an existing entry. + +Examples +~~~~~~~~ + +Generate an ``openrc`` file for sourcing: + +.. code-block:: bash + + cc-login --output-openrc ~/openrc_chameleon + +Add or update a cloud entry in ``clouds.yaml``: + +.. code-block:: bash + + cc-login --output-clouds-yaml ~/.config/openstack/clouds.yaml \ + --cloud-name chameleon + +Force a fresh device authentication (ignoring cache): + +.. code-block:: bash + + cc-login --force-refresh + diff --git a/source/technical/cli/index.rst b/source/technical/cli/index.rst index 02ac8a2..230fc14 100644 --- a/source/technical/cli/index.rst +++ b/source/technical/cli/index.rst @@ -30,4 +30,5 @@ the client and configure your shell environment to access Chameleon features. installation authentication rc_script + cc_login usage \ No newline at end of file From 60b347e90c82865f491ebc99830c5ed1a2791df4 Mon Sep 17 00:00:00 2001 From: Paul Marshall Date: Wed, 25 Mar 2026 16:30:45 -0500 Subject: [PATCH 2/3] Address PR feedback: add note to rc script page directing users to cc-login --- source/technical/cli/rc_script.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/source/technical/cli/rc_script.rst b/source/technical/cli/rc_script.rst index e6d1b05..9977f71 100644 --- a/source/technical/cli/rc_script.rst +++ b/source/technical/cli/rc_script.rst @@ -16,6 +16,13 @@ Chameleon GUI at the :ref:`gui-api-access`. directly, as well as the :ref:`cc-snapshot utility ` tool. +.. note:: + + On an instance running a CC-* image, you can use the :ref:`cc-login ` + command to generate a new openrc file or clouds.yaml entry with an application + credential. This is useful for creating fresh credentials without + accessing the Chameleon GUI. + #. Log in to the GUI at |CHI@TACC| or |CHI@UC|. .. important:: From 921b8fae0b2fa2dedc4e87eee4f524eb38811108 Mon Sep 17 00:00:00 2001 From: Paul Marshall Date: Wed, 25 Mar 2026 16:44:11 -0500 Subject: [PATCH 3/3] Address PR feedback: clarify device auth flow, add an exmaple workflow --- source/technical/cli/cc_login.rst | 36 ++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/source/technical/cli/cc_login.rst b/source/technical/cli/cc_login.rst index d2ae710..e71557f 100644 --- a/source/technical/cli/cc_login.rst +++ b/source/technical/cli/cc_login.rst @@ -9,6 +9,18 @@ application credential for reuse, and can generate OpenStack ``openrc`` files or entries for ``clouds.yaml`` so the OpenStack CLI and libraries can use the cached credential. +The device authentication flow directs you to a URL in your browser where you +log in with your Chameleon credentials and approve the device request. Once +approved, ``cc-login`` creates an application credential on your behalf and +caches it for reuse, so subsequent OpenStack operations do not require +authentication. + +.. warning:: + + Authentication information provided through instance vendor-data is + being deprecated. Use ``cc-login`` to obtain fresh application credentials + instead. + Usage ~~~~~ @@ -38,20 +50,38 @@ and output format. Some of the most commonly used ones are: Examples ~~~~~~~~ -Generate an ``openrc`` file for sourcing: +Complete workflow: Authenticating and running OpenStack commands +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +To authenticate and run commands like ``openstack image list``, you have two options +to use credentials obtained via ``cc-login``: + +**Option 1: Source an openrc file** + +Generate an ``openrc`` file and source it in your shell session: .. code-block:: bash cc-login --output-openrc ~/openrc_chameleon + source ~/openrc_chameleon + openstack image list -Add or update a cloud entry in ``clouds.yaml``: +**Option 2: Use clouds.yaml** + +Alternatively, generate or update an entry in ``clouds.yaml`` and use the +``OS_CLOUD`` environment variable: .. code-block:: bash cc-login --output-clouds-yaml ~/.config/openstack/clouds.yaml \ --cloud-name chameleon + export OS_CLOUD=chameleon + openstack image list + +Other examples ++++++++++++++++ -Force a fresh device authentication (ignoring cache): +Force a fresh device authentication (ignoring the local cache): .. code-block:: bash