diff --git a/doc/source/security/kubernetes/manage-local-ldap-39fe3a85a528.rst b/doc/source/security/kubernetes/manage-local-ldap-39fe3a85a528.rst index d58e36b6f..8e6c6b258 100644 --- a/doc/source/security/kubernetes/manage-local-ldap-39fe3a85a528.rst +++ b/doc/source/security/kubernetes/manage-local-ldap-39fe3a85a528.rst @@ -9,8 +9,11 @@ Manage Composite Local LDAP Accounts at Scale The purpose of this playbook is to simplify and automate the management of composite Local |LDAP| accounts across multiple |DC| systems or standalone systems. A composite Local |LDAP| account is defined as a Local |LDAP| account -that also has a unique keystone account with admin role credentials and access -to a K8S serviceAccount with ``cluster-admin`` role credentials. +that also has a unique Keystone account with same name (in the Admin Project) +and a specified Keystone role. The Local |LDAP| account can be optionally set +with ``sudo`` and/or ``sys_protected`` privileges. If the created |LDAP| account +is assigned ``sys_protected`` privileges, it will have access to a K8S +serviceAccount with ``cluster-admin`` role credentials. A user with such a composite Local |LDAP| account can |SSH| to systems' controllers and subclouds and: @@ -18,24 +21,19 @@ controllers and subclouds and: - execute Linux commands (with local |LDAP| account credentials; with or without sudo capabilities), -- execute |prod| |CLI| commands (with its keystone account (admin role) - credentials) and +- execute |prod| |CLI| commands (with its Keystone account credentials) and -- execute K8S |CLI| commands (with credentials of a ``cluster-admin`` K8S - serviceAccount). +- execute K8S |CLI| commands if the |LDAP| account has ``sys_protected`` + privileges (with credentials of a ``cluster-admin`` K8S serviceAccount). -A unique Local |LDAP| account and unique keystone account enables user-specific +A unique Local |LDAP| account and unique Keystone account enables user-specific command audit logging for security and tracking purposes. -Besides creating the required Local |LDAP|, Keystone and K8S accounts, the -playbook also fully sets up Keystone and K8S credentials in the Local |LDAP| -user's home directory on all controllers of all systems (i.e. standalone -systems, |DC| SystemControllers and |DC| Subclouds). - The playbook can be used to create or delete such composite Local |LDAP| Accounts, manage access to sudo capabilities and manage password change parameters. + ----------------------------------------- Create inventory file using Ansible-Vault ----------------------------------------- @@ -51,25 +49,21 @@ Create a secure inventory file: ~(keystone_admin)]$ ansible-vault create secure-inventory - This will open a text editor where you can fill the inventory parameters as -shown on the example below: +shown in the example below. When this ansible playbook runs locally, this +inventory will always have the same contents except for the value of +````. .. code-block:: none [all:vars] - ansible_user=sysadmin - ansible_password= - ansible_become_pass= [systemcontroller] - systemcontroller-0 ansible_host=127.0.0.1 - The inventory parameters are: ``ansible_user`` @@ -87,6 +81,7 @@ The inventory parameters are: address, if running the ansible playbook locally on the target |DC|/Standalone system controller. + ---------------- Run the playbook ---------------- @@ -99,23 +94,24 @@ password will be prompted during runtime. ~(keystone_admin)]$ ansible-playbook --inventory secure-inventory --ask-vault-pass --extra-vars='user_id=na-admin mode=create' /usr/share/ansible/stx-ansible/playbooks/manage_local_ldap_account.yml -- Extra-vars parameter options: +Extra-vars parameter options: - ``user_id`` +- ``user_id`` + + ```` Username that will be used for both the Local |LDAP| account and the - Keystone account on the target |DC|/Standalone system and associated - |DC| Subclouds. + Keystone account (in the Admin Project) on the target |DC|/Standalone + system and associated |DC| Subclouds. -- mode: +- ``mode`` (optional, default is "create"): ``create`` - Creates users within Local |LDAP| and Keystone. This is the default - value when not specified. + Creates users within Local |LDAP| and Keystone. ``delete`` Removes existing users from Local |LDAP| and Keystone. -- ``sudo_permission`` (optional): +- ``sudo_permission`` (optional, default is "no"): ``yes`` The created Local |LDAP| user will have ``sudo`` capabilities to @@ -127,31 +123,109 @@ password will be prompted during runtime. execute commands with root privileges on the |DC|/Standalone system and associated |DC| Subclouds. -- ``user_role`` (optional): +- ``sys_protected`` (optional, default is "no"): + + ``yes`` + The created Local |LDAP| user will be added to ``sys_protected`` group, + and will be able to access a K8S serviceAccount with ``cluster-admin`` + role credentials. + + ``no`` + The created Local |LDAP| user will NOT be added to ``sys_protected`` + group. + +- ``user_role`` (optional, default is "admin"): ``admin`` - Set the keystone role of the user to be created as ``admin``. - This role has permissions to execute all StarlingX CLI commands. - This is the default value when not specified. + Set the Keystone role of the user to be created as ``admin``. + This role has permissions to execute all |prod| CLI commands. ``member`` - Set the keystone role of the user to be created as ``member``. + Set the Keystone role of the user to be created as ``member``. This role is for future use, currently it has the same permissions as - keystone ``reader`` role. + Keystone ``reader`` role. ``reader`` - Set the keystone role of the user to be created as ``reader``. + Set the Keystone role of the user to be created as ``reader``. This role has permissions to only execute passive display-type - (e.g. list, get) StarlingX CLI commands. + (e.g. list, get) |prod| CLI commands. -- ``password_change_period``: +- ``password_change_period`` (optional, default is "90"): ```` - Related to the /etc/shadow file, this attribute specifies the maximum - number of days that the Local |LDAP| account's is valid. + Specifies the maximum number of days that the Local |LDAP| account's + password is valid. -- ``password_warning_period``: +- ``password_warning_period`` (optional, default is "2"): ```` - Related to the /etc/shadow file, this attribute specifies the number - of days before password expiration that the Local |LDAP| user is warned. + Specifies the number of days before password expiration that the Local + |LDAP| user is warned. + + +--------------------------------------------- +Use the created composite Local LDAP accounts +--------------------------------------------- + +For subclouds that were "managed" and with identity_sync_status "in-sync" when +the playbook run (this can be checked with command `dcmanager subcloud show +`), it may take up to 2 minutes for the created Keystone account +to propagate to these subclouds. + +For subclouds that are not "managed" or were added after the playbook run, it is +sufficient to set these subclouds as "managed" and wait for them to have +identity_sync_status "in-sync". + +If the created Local |LDAP| user has sudo permission, it may take up to 5 +minutes for this permission to reach all nodes. + +To test the created composite Local |LDAP| account, |SSH| to a cloud and +execute: + +.. code-block:: none + + $ source local_starlingxrc + Enter the password to be used with Keystone user na-admin: + Created file /home/na-admin/na-admin-openrc + ~(keystone_na-admin)]$ system host-list + +----+--------------+-------------+----------------+-------------+--------------+ + | id | hostname | personality | administrative | operational | availability | + +----+--------------+-------------+----------------+-------------+--------------+ + | 1 | controller-0 | controller | unlocked | enabled | available | + +----+--------------+-------------+----------------+-------------+--------------+ + +The operator should always execute `source local_starlingxrc` to load Keystone +credentials. This command prompts the user for the Keystone password, stores it +in the local file ``-openrc`` and loads it. Subsequent calls of `source +local_starlingxrc` will just load the created local openrc file. + + +--------------- +Troubleshooting +--------------- + +This section describes common problems and their solutions. + +.. code-block:: none + + ~(keystone_na-admin)]$ system host-list + Must provide Keystone credentials or user-defined endpoint and token, error was: The request you have made requires authentication. (HTTP 401) + +The error above happens either because the Keystone password is wrong and/or +because the Keystone user has not been propagated to all subclouds. Check if the +password is correct in the contents of the local file ``-openrc``. Check +the system controller if all subclouds are "managed" and with +identity_sync_status "in-sync". Wait for 2 minutes after the playbook is run for +Keystone user propagation in the subclouds that are already in a "managed" +state, and with identity_sync_status "in-sync". + +.. code-block:: none + + ~(keystone_na-admin)]$ sudo ls -la + Password: + na-admin is not allowed to run sudo on controller-0. This incident will be reported. + +The error above happens either because the |LDAP| account was created without +sudo permission or because the sudo permission for this |LDAP| account did not +reach the current node. Check if the playbook was run with +``sudo_permission=yes``. Wait 5 minutes for sudo permission to sync.