diff --git a/doc/source/index.rst b/doc/source/index.rst index e369979b8..e377b63be 100755 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -75,6 +75,15 @@ Data Network Configuration and Management Guides datanet/index +-------------------- +System Configuration +-------------------- + +.. toctree:: + :maxdepth: 2 + + system_configuration/index + ---------------- Fault Management ---------------- @@ -90,7 +99,7 @@ User Tasks .. toctree:: :maxdepth: 2 - + usertasks/index ---------------- @@ -145,4 +154,4 @@ governance. .. _`OpenStack Foundation Board of Directors`: https://wiki.openstack.org/wiki/Governance/Foundation .. _`StarlingX Technical Steering Committee`: https://docs.starlingx.io/governance/reference/tsc/ -.. _`StarlingX Governance`: https://docs.starlingx.io/governance/ \ No newline at end of file +.. _`StarlingX Governance`: https://docs.starlingx.io/governance/ diff --git a/doc/source/shared/strings.txt b/doc/source/shared/strings.txt index b17177bd1..80e9707d0 100644 --- a/doc/source/shared/strings.txt +++ b/doc/source/shared/strings.txt @@ -1,4 +1,4 @@ -.. Common string substitutions for brand customization. +.. Common string substitutions for brand customization and consistency. .. NOTE: Do not use underscores in these substitution names. .. For more information, see .. https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions @@ -11,7 +11,7 @@ .. |prod-long| replace:: StarlingX .. |prod-os| replace:: StarlingX OpenStack -.. Guide names, will be formatted in italics by default. +.. Guide names; will be formatted in italics by default. .. |node-doc| replace:: :title:`StarlingX Node Configuration and Management` .. |planning-doc| replace:: :title:`StarlingX Planning` .. |sec-doc| replace:: :title:`StarlingX Security` @@ -41,27 +41,65 @@ .. Name of downloads location .. |dnload-loc| replace:: a StarlingX mirror -.. File name prefix, as in stx-remote-cli-.tgz. May also be -.. used in sample domain names etc. +.. File name prefix, as in stx-remote-cli-.tgz. May also be + used in sample domain names etc. + .. |prefix| replace:: stx +.. space character. Needed for padding in tabular output. Currently + used where |prefix| replacement is a length shorter than 3. + To insert a space, use "replace:: \ \" (with two spaces) + To insert no spaces, use "replace:: \" + +.. |s| replace:: \ + .. Common and domain-specific sbbreviations. .. Plural forms must be defined seperately from singular as .. replacements like |PVC|s won't work. +.. Please keep this list alphabetical. + +.. |AE| replace:: :abbr:`AE (Aggregated Ethernet)` +.. |AIO| replace:: :abbr:`AIO (All-In-One)` +.. |AVS| replace:: :abbr:`AVS (Application Virtual Switch)` .. |BGP| replace:: :abbr:`BGP (Border Gateway Protocol)` +.. |BMC| replace:: :abbr:`BMC (Board Management Controller)` +.. |BMCs| replace:: :abbr:`BMCs (Board Management Controllers)` .. |CNI| replace:: :abbr:`CNI (Container Networking Interface)` +.. |CSK| replace:: :abbr:`CSK (Code Signing Key)` +.. |CSKs| replace:: :abbr:`CSKs (Code Signing Keys)` +.. |DPDK| replace:: :abbr:`DPDK (Data Plane Development Kit)` +.. |FEC| replace:: :abbr:`FEC (Forward Error Correction)` +.. |FPGA| replace:: :abbr:`FPGA (Field Programmable Gate Array)` +.. |GNP| replace:: :abbr:`GNP (Global Network Policy)` .. |IPMI| replace:: :abbr:`IPMI (Intelligent Platform Management Interface)` +.. |LACP| replace:: :abbr:`LACP (Link Aggregation Control Protocol)` .. |LAG| replace:: :abbr:`LAG (Link Aggregation)` .. |LDAP| replace:: :abbr:`LDAP (Lightweight Directory Access Protocol)` +.. |LDPC| replace:: :abbr:`LDPC (Low-Density Parity Check)` +.. |LLDP| replace:: :abbr:`LLDP (Link Layer Discovery Protocol)` +.. |MTU| replace:: :abbr:`MTU (Maximum Transmission Unit)` +.. |MAC| replace:: :abbr:`MAC (Media Access Control)` .. |MEC| replace:: :abbr:`MEC (Multi-access Edge Computing)` -.. |NVMe| replace:: :abbr:`NVMe (Non Volatile Memory express)` +.. |MNFA| replace:: :abbr:`MNFA (Multi-Node Failure Avoidance)` +.. |MOTD| replace:: :abbr:`MOTD (Message of the Day)` +.. |NIC| replace:: :abbr:`NIC (Network Interface Card)` +.. |NICs| replace:: :abbr:`NICs (Network Interface Cards)` +.. |NTP| replace:: :abbr:`NTP (Network Time Protocol)` +.. |NUMA| replace:: :abbr:`NUMA (Non-Uniform Memory Access)` +.. |NVMe| replace:: :abbr:`NVMe (Non-Volatile Memory express)` .. |OAM| replace:: :abbr:`OAM (Operations, administration and management)` .. |OSD| replace:: :abbr:`OSD (Object Storage Device)` .. |OSDs| replace:: :abbr:`OSDs (Object Storage Devices)` +.. |PAC| replace:: :abbr:`PAC (Programmable Acceleration Card)` +.. |PCI| replace:: :abbr:`PCI (Peripheral Component Interconnect)` +.. |PDU| replace:: :abbr:`PDU (Packet Data Unit)` +.. |PTP| replace:: :abbr:`PTP (Precision Time Protocol)` .. |PVC| replace:: :abbr:`PVC (Persistent Volume Claim)` .. |PVCs| replace:: :abbr:`PVCs (Persistent Volume Claims)` .. |PXE| replace:: :abbr:`PXE (Preboot Execution Environment)` +.. |QoS| replace:: :abbr:`QoS (Quality of Service)` +.. |RPC| replace:: :abbr:`RPC (Remote Procedure Call)` .. |SAS| replace:: :abbr:`SAS (Serial Attached SCSI)` .. |SATA| replace:: :abbr:`SATA (Serial AT Attachment)` .. |SNMP| replace:: :abbr:`SNMP (Simple Network Management Protocol)` @@ -69,4 +107,9 @@ .. |SSD| replace:: :abbr:`SSD (Solid State Drive)` .. |SSH| replace:: :abbr:`SSH (Secure Shell)` .. |ToR| replace:: :abbr:`ToR (Top-of-Rack)` - +.. |UDP| replace:: :abbr:`UDP (User Datagram Protocol)` +.. |VLAN| replace:: :abbr:`VLAN (Virtual Local Area Network)` +.. |VM| replace:: :abbr:`VM (Virtual Machine)` +.. |VMs| replace:: :abbr:`VMs (Virtual Machines)` +.. |VNC| replace:: :abbr:`VNC (Virtual Network Computing)` +.. |VXLAN| replace:: :abbr:`VXLAN (Virtual eXtensible Local Area Network)` diff --git a/doc/source/system_configuration/adding-configuration-rpc-response-max-timeout-in-neutron-conf.rst b/doc/source/system_configuration/adding-configuration-rpc-response-max-timeout-in-neutron-conf.rst new file mode 100644 index 000000000..85110216d --- /dev/null +++ b/doc/source/system_configuration/adding-configuration-rpc-response-max-timeout-in-neutron-conf.rst @@ -0,0 +1,54 @@ + +.. gkr1591372948568 +.. _adding-configuration-rpc-response-max-timeout-in-neutron-conf: + +======================================================== +Add Configuration rpc\_response\_max\_timeout in Neutron +======================================================== + +You can add the rpc\_response\_max\_timeout to Neutron using Helm +overrides. + +.. rubric:: |context| + +Maximum rpc timeout is now configurable by rpc\_response\_max\_timeout from +Neutron config instead of being calculated as 10 \* rpc\_response\_timeout. + +This configuration can be used to change the maximum rpc timeout. If the +maximum rpc timeout is too big, some requests which should fail will be held +for a long time before the server returns failure. If this value is too small +and the server is very busy, the requests may need more time than maximum rpc +timeout and the requests will fail though they can succeed with a bigger +maximum rpc timeout. + +.. rubric:: |proc| + +1. Create a yaml file to add configuration rpc\_response\_max\_timeout in + Neutron. + + .. code-block:: none + + ~(keystone_admin)]$ cat > neutron-overrides.yaml < -n openstack – cat /etc/neutron/neutron.conf | grep rpc_response_max_timeout + rpc_response_max_timeout = 600 + $ cat /etc/neutron/neutron.conf | grep rpc_response_max_timeout \ No newline at end of file diff --git a/doc/source/system_configuration/application-commands-and-helm-overrides.rst b/doc/source/system_configuration/application-commands-and-helm-overrides.rst new file mode 100644 index 000000000..6d3d8c67a --- /dev/null +++ b/doc/source/system_configuration/application-commands-and-helm-overrides.rst @@ -0,0 +1,469 @@ + +.. hby1568295041837 +.. _sysconf-application-commands-and-helm-overrides: + +======================================= +Application Commands and Helm Overrides +======================================= + +Use |prod| :command:`system application` and :command:`system helm-override` +commands to manage containerized applications provided as part of |prod|. + +.. rubric:: |proc| + +- Use the following command to list all containerized applications provided + as part of |prod|. + + .. code-block:: none + + ~(keystone_admin)$ system application-list [--nowrap] + + where: + + ``--nowrap`` + prevents line wrapping of the output. + + For example: + + .. parsed-literal:: + + ~(keystone_admin)$ system application-list --nowrap + + +-------------+---------+---------------+----------------+----------+-----------+ + | application | version | manifest name | manifest file | status | progress | + +-------------+---------+---------------+----------------+----------+-----------+ + | platform- | 1.0-7 | platform- | manifest.yaml | applied | completed | + | integ-apps | | integration- | | | | + | | | manifest | | | | + | |prefix|- |s| | 1.0-18 | armada- | |prefix|-openstack |s| | uploaded | completed | + | openstack | | manifest | .yaml | | | + +-------------+---------+---------------+----------------+----------+-----------+ + +- Use the following command to show details for |prod|. + + .. code-block:: none + + ~(keystone_admin)$ system application-show + + where: + + **** + is the name of the application to show details for. + + For example: + + .. parsed-literal:: + + ~(keystone_admin)$ system application-show |prefix|-openstack + + +---------------+----------------------------------+ + | Property | Value | + +---------------+----------------------------------+ + | active | False | + | app_version | 1.0-18 | + | created_at | 2019-09-06T15:34:03.194150+00:00 | + | manifest_file | |prefix|-openstack.yaml |s| | + | manifest_name | armada-manifest | + | name | |prefix|-openstack |s| | + | progress | completed | + | status | uploaded | + | updated_at | 2019-09-06T15:34:46.995929+00:00 | + +---------------+----------------------------------+ + +- Use the following command to upload application helm chart\(s\) and + manifest. + + .. code-block:: none + + ~(keystone_admin)$ system application-upload [-n | --app-name] [-v | --version] + + where the following are optional arguments: + + **** + assigns a custom name for application. You can use this name to + interact with the application in the future. + + **** + is the version of the application. + + and the following is a positional argument: + + **** + is the path to the tar file containing the application to be uploaded. + + For example: + + .. parsed-literal:: + + ~(keystone_admin)$ system application-upload |prefix|-openstack-1.0-18.tgz + +---------------+----------------------------------+ + | Property | Value | + +---------------+----------------------------------+ + | active | False | + | app_version | 1.0-18 | + | created_at | 2019-09-06T15:34:03.194150+00:00 | + | manifest_file | |prefix|-openstack.yaml | + | manifest_name | armada-manifest | + | name | |prefix|-openstack | + | progress | None | + | status | uploading | + | updated_at | None | + +---------------+----------------------------------+ + Please use 'system application-list' or 'system application-show |prefix|-openstack' to view the current progress. + +- To list the helm chart overrides for the |prod|, use the following + command: + + .. code-block:: none + + ~(keystone_admin)$ system helm-override-list + usage: system helm-override-list [--nowrap] [-l | --long] + + where the following is a positional argument: + + **** + The name of the application. + + and the following are optional arguments: + + ``--nowrap`` + No word-wrapping of output. + + ``--long`` + List additional fields in output. + + For example: + + .. parsed-literal:: + + ~(keystone_admin)$ system helm-override-list |prefix|-openstack --long + +---------------------+--------------------------------+---------------+ + | chart name | overrides namespaces | chart enabled | + +---------------------+--------------------------------+---------------+ + | aodh | [u'openstack'] | [False] | + | barbican | [u'openstack'] | [False] | + | ceilometer | [u'openstack'] | [False] | + | ceph-rgw | [u'openstack'] | [False] | + | cinder | [u'openstack'] | [True] | + | garbd | [u'openstack'] | [True] | + | glance | [u'openstack'] | [True] | + | gnocchi | [u'openstack'] | [False] | + | heat | [u'openstack'] | [True] | + | helm-toolkit | [] | [] | + | horizon | [u'openstack'] | [True] | + | ingress | [u'kube-system', u'openstack'] | [True, True] | + | ironic | [u'openstack'] | [False] | + | keystone | [u'openstack'] | [True] | + | keystone-api-proxy | [u'openstack'] | [True] | + | libvirt | [u'openstack'] | [True] | + | mariadb | [u'openstack'] | [True] | + | memcached | [u'openstack'] | [True] | + | neutron | [u'openstack'] | [True] | + | nginx-ports-control | [] | [] | + | nova | [u'openstack'] | [True] | + | nova-api-proxy | [u'openstack'] | [True] | + | openvswitch | [u'openstack'] | [True] | + | panko | [u'openstack'] | [False] | + | placement | [u'openstack'] | [True] | + | rabbitmq | [u'openstack'] | [True] | + | version_check | [] | [] | + +---------------------+--------------------------------+---------------+ + +- To show the overrides for a particular chart, use the following command. + System overrides are displayed in the **system\_overrides** section of + the **Property** column. + + .. code-block:: none + + ~(keystone_admin)$ system helm-override-show + usage: system helm-override-show + + where the following are positional arguments: + + **** + The name of the application. + + **< chart\_name>** + The name of the chart. + + **** + The namespace for chart overrides. + + For example: + + .. code-block:: none + + ~(keystone_admin)$ system helm-override-show |prefix|-openstack glance openstack + +- To modify service configuration parameters using user-specified overrides, + use the following command. To update a single configuration parameter, you + can use ``--set``. To update multiple configuration parameters, use + the ``--values`` option with a **yaml** file. + + .. code-block:: none + + ~(keystone_admin)$ system helm-override-update + usage: system helm-override-update --reuse-values --reset-values --values --set + + where the following are positional arguments: + + **** + The name of the application. + + **** + The name of the chart. + + **** + The namespace for chart overrides. + + and the following are optional arguments: + + ``--reuse-values`` + Reuse existing helm chart user override values. If reset-values is + used, reuse-values is ignored. + + ``--reset-values`` + Replace any existing helm chart overrides with the ones specified. + + ``--values`` + Specify a **yaml** file containing helm chart override values. You can + specify this value multiple times. + + ``--set`` + Set helm chart override values using the command line. Multiple + override values can be specified with multiple :command:`set` + arguments. These are processed after files passed through the + values argument. + + For example, to enable the glance debugging log, use the following + command: + + .. parsed-literal:: + + ~(keystone_admin)$ system helm-override-update |prefix|-openstack glance openstack --set conf.glance.DEFAULT.DEBUG=true + +----------------+-------------------+ + | Property | Value | + +----------------+-------------------+ + | name | glance | + | namespace | openstack | + | user_overrides | conf: | + | | glance: | + | | DEFAULT: | + | | DEBUG: true | + +----------------+-------------------+ + + The user overrides are shown in the **user\_overrides** section of the + **Property** column. + + .. note:: + To apply the updated helm chart ovverrides to the running application, + use the :command:`system application-apply` command. + +- To enable or disable the installation of a particular helm chart within an + application manifest, use the :command:`helm-chart-attribute-modify` + command. This command does not modify a chart or modify chart overrides, + which are managed through the :command:`helm-override-update` command. + + .. code-block:: none + + ~(keystone_admin)$ system helm-chart-attribute-modify [--enabled ] + + where the following is an optional argument: + + ``--enabled`` + determines whether the chart is enabled. + + and the following are positional arguments: + + **** + The name of the application. + + **** + The name of the chart. + + **** + The namespace for chart overrides. + + .. note:: + To apply the updated helm chart attribute to the running application, + use the :command:`system application-apply` command. + +- To delete all the user overrides for a chart, use the following command: + + .. code-block:: none + + ~(keystone_admin)$ system helm-override-delete + usage: system helm-override-delete + + where the following are positional arguments: + + **** + The name of the application. + + **** + The name of the chart. + + **** + The namespace for chart overrides. + + For example: + + .. parsed-literal:: + + ~(keystone_admin)$ system helm-override-delete |prefix|-openstack glance openstack + Deleted chart overrides glance:openstack for application |prefix|-openstack + +- Use the following command to apply or reapply an application, making it + available for service. + + .. code-block:: none + + ~(keystone_admin)$ system application-apply [-m | --mode] + + where the following is an optional argument: + + **mode** + An application-specific mode controlling how the manifest is + applied. This option is used to back-up and restore the + **|prefix|-openstack** application. + + and the following is a positional argument: + + **** + is the name of the application to apply. + + For example: + + .. parsed-literal:: + + ~(keystone_admin)$ system application-apply |prefix|-openstack + +---------------+----------------------------------+ + | Property | Value | + +---------------+----------------------------------+ + | active | False | + | app_version | 1.0-18 | + | created_at | 2019-09-06T15:34:03.194150+00:00 | + | manifest_file | |prefix|-openstack.yaml |s| | + | manifest_name | armada-manifest | + | name | |prefix|-openstack |s| | + | progress | None | + | status | applying | + | updated_at | 2019-09-06T15:34:46.995929+00:00 | + +---------------+----------------------------------+ + Please use 'system application-list' or 'system application-show |prefix|-openstack' to view the current progress. + +- Use the following command to abort the current application. + + .. code-block:: none + + ~(keystone_admin)$ system application-abort + + where: + + **** + is the name of the application to abort. + + For example: + + .. code-block:: none + + ~(keystone_admin)$ system application-abort |prefix|-openstack + Application abort request has been accepted. If the previous operation has not + completed/failed, it will be cancelled shortly. + + Use :command:`application-list` to confirm that the application has been + aborted. + +- Use the following command to update the deployed application to a different + version. + + .. code-block:: none + + ~(keystone_admin)$ system application-update [-n | --app-name] [-v | --app-version] + + where the following are optional arguments: + + **** + The name of the application to update. + + You can look up the name of an application using the :command:`application-list` command: + + .. code-block:: none + + ~(keystone_admin)$ system application-list + +--------------------------+----------+-------------------------------+---------------------------+----------+-----------+ + | application | version | manifest name | manifest file | status | progress | + +--------------------------+----------+-------------------------------+---------------------------+----------+-----------+ + | cert-manager | 20.06-4 | cert-manager-manifest | certmanager-manifest.yaml | applied | completed | + | nginx-ingress-controller | 20.06-1 | nginx-ingress-controller- | nginx_ingress_controller | applied | completed | + | | | -manifest | _manifest.yaml | | | + | oidc-auth-apps | 20.06-26 | oidc-auth-manifest | manifest.yaml | uploaded | completed | + | platform-integ-apps | 20.06-9 | platform-integration-manifest | manifest.yaml | applied | completed | + +--------------------------+----------+-------------------------------+---------------------------+----------+-----------+ + + The output indicates that the currently installed version of **cert-manager** is 20.06-4. + + **** + The version to update the application to. + + and the following is a positional argument which must come last: + + **** + The tar file containing the application manifest, Helm charts and + configuration file. + +- Use the following command to remove an application from service. Removing + an application will clean up related Kubernetes resources and delete all + of its installed helm charts. + + .. code-block:: none + + ~(keystone_admin)$ system application-remove + + where: + + **** + is the name of the application to remove. + + For example: + + .. parsed-literal:: + + ~(keystone_admin)$ system application-remove |prefix|-openstack + +---------------+----------------------------------+ + | Property | Value | + +---------------+----------------------------------+ + | active | False | + | app_version | 1.0-18 | + | created_at | 2019-09-06T15:34:03.194150+00:00 | + | manifest_file | |prefix|-openstack.yaml |s| | + | manifest_name | armada-manifest | + | name | |prefix|-openstack |s| | + | progress | None | + | status | removing | + | updated_at | 2019-09-06T17:39:19.813754+00:00 | + +---------------+----------------------------------+ + Please use 'system application-list' or 'system application-show |prefix|-openstack' to view the current progress. + + This command places the application in the uploaded state. + +- Use the following command to completely delete an application from the + system. + + .. code-block:: none + + ~(keystone_admin)$ system application-delete + + where: + + **** + is the name of the application to delete. + + You must run :command:`application-remove` before deleting an application. + + For example: + + .. parsed-literal:: + + ~(keystone_admin)$ system application-delete |prefix|-openstack + Application |prefix|-openstack deleted. \ No newline at end of file diff --git a/doc/source/system_configuration/applying-a-custom-branding-tarball-to-newly-installed-systems.rst b/doc/source/system_configuration/applying-a-custom-branding-tarball-to-newly-installed-systems.rst new file mode 100644 index 000000000..29f053b86 --- /dev/null +++ b/doc/source/system_configuration/applying-a-custom-branding-tarball-to-newly-installed-systems.rst @@ -0,0 +1,20 @@ + +.. hur1582149306886 +.. _applying-a-custom-branding-tarball-to-newly-installed-systems: + +========================================================== +Apply a Custom Branding Tarball to Newly Installed Systems +========================================================== + +You can apply a custom branding tarball to newly installed systems +prior to running the bootstrap playbook. + +Complete the following steps to apply the custom branding tarball: + +.. rubric:: |proc| + +#. Copy the branding tarball to the /opt/branding directory. + +#. Run the Ansible bootstrap playbook. + + The branding will be automatically updated on the Horizon Web interface. \ No newline at end of file diff --git a/doc/source/system_configuration/applying-a-custom-branding-tarball-to-running-systems.rst b/doc/source/system_configuration/applying-a-custom-branding-tarball-to-running-systems.rst new file mode 100644 index 000000000..6e953b8ae --- /dev/null +++ b/doc/source/system_configuration/applying-a-custom-branding-tarball-to-running-systems.rst @@ -0,0 +1,28 @@ + +.. cmk1582149379500 +.. _applying-a-custom-branding-tarball-to-running-systems: + +================================================== +Apply a Custom Branding Tarball to Running Systems +================================================== + +You can apply the custom branding tarball to running systems. + +Complete the following steps to apply the custom branding tarball: + +.. rubric:: |proc| + +.. _applying-a-custom-branding-tarball-to-running-systems-steps-ayv-tqy-hkb: + +#. Delete any previous branding tarball from /opt/branding. + +#. Copy the new branding tarball to the /opt/branding directory on the + active controller. + +#. Restart the Horizon Web interface. + + .. code-block:: none + + # sudo service horizon restart + +#. Lock, and unlock the inactive controller to apply the new configuration. \ No newline at end of file diff --git a/doc/source/system_configuration/assigning-a-dedicated-vlan-id-to-a-target-project-network.rst b/doc/source/system_configuration/assigning-a-dedicated-vlan-id-to-a-target-project-network.rst new file mode 100644 index 000000000..3c83b05f1 --- /dev/null +++ b/doc/source/system_configuration/assigning-a-dedicated-vlan-id-to-a-target-project-network.rst @@ -0,0 +1,191 @@ + +.. dkn1600946881404 +.. _dkn1600946881404: + +====================================================== +Assign a Dedicated VLAN ID to a Target Project Network +====================================================== + +To assign a dedicated VLAN segment ID you must first enable the Neutron +**segments** plugin. + +.. rubric:: |proc| + +#. Create a Helm overrides file to customize your Neutron configuration. + + The file must load the **segments** plugin. For example: + + .. code-block:: none + + ... + conf: + neutron: + DEFAULT: + service_plugins: + - router + - network_segment_range + - segments + ... + +#. If you have not done so already, upload the |prefix|-openstack application + charts. + + For example: + + .. parsed-literal:: + + ~(keystone_admin)]$ system application-upload |prefix|-openstack-20.10-0.tgz + +#. Update the |prefix|-openstack application using the overrides file created above. + + Assuming you named the file neutron-overrides.yaml, run: + + .. parsed-literal:: + + ~(keystone_admin)]$ system helm-override-update |prefix|-openstack neutron openstack --values neutron-overrides.yaml + + You can check on the status of the update using the + :command:`system helm-override-show` command. For example: + + .. parsed-literal:: + + ~(keystone_admin)]$ system helm-override-show |prefix|-openstack neutron openstack + +--------------------+---------------------------------------------------------------------------------------------------------------------+ + | Property | Value | + +--------------------+---------------------------------------------------------------------------------------------------------------------+ + | attributes | enabled: true | + | | | + | combined_overrides | conf: | + | | dhcp_agent: | + | | DEFAULT: | + | | interface_driver: networking_avs.neutron.agent.avs_manager.interface.VSwitchInterfaceDriver | + | | neutron: | + | | | + | ... | ... | + | | | + | user_overrides | conf: | + | | neutron: | + | | DEFAULT: | + | | service_plugins: | + | | - router | + | | - network_segment_range | + | | - segments | + | | | + +--------------------+---------------------------------------------------------------------------------------------------------------------+ + + +#. Apply the |prefix|-openstack application. + + .. parsed-literal:: + + ~(keystone_admin)]$ system application-apply |prefix|-openstack + +#. You can now assign the VLAN network type to a datanetwork. + + #. Identify the name of the data network to assign. + + List the available data networks and identify one to use in the heat + template as: + + .. code-block:: none + + physical_network: + + In this example, we use **datanet-1**. + + #. Create a heat template. + + For example: + + .. code-block:: none + + ~(keystone_admin)]$ cat < my_heat_template.yml + heat_template_version: 2017-09-01 + + resources: + + external01: + type: OS::Neutron::Net + properties: + name: external001 + shared: "true" + + # Network segement + segement01: + type: OS::Neutron::Segment + properties: + network: { get_resource: external01 } + network_type: "vlan" + physical_network: "datanet-1" + segmentation_id: 2111 + + external01-subnet: + type: OS::Neutron::Subnet + properties: + network: { get_resource: external01 } + name: external02-subnet + cidr: 10.10.10.0/24 + segment: { get_resource: segement01 } + EOF + + #. Apply the template. + + .. code-block:: none + + ~(keystone_admin)]$ OS_AUTH_URL=http://keystone.openstack.svc.cluster.local/v3 + ~(keystone_admin)]$ openstack stack create -t my_heat_template.yml --wait test1-st + 2020-10-16 21:20:34Z [test1-st]: CREATE_IN_PROGRESS Stack CREATE started + 2020-10-16 21:20:34Z [test1-st.external01]: CREATE_IN_PROGRESS state changed + 2020-10-16 21:20:35Z [test1-st.external01]: CREATE_COMPLETE state changed + 2020-10-16 21:20:35Z [test1-st.segement01]: CREATE_IN_PROGRESS state changed + 2020-10-16 21:20:37Z [test1-st.segement01]: CREATE_COMPLETE state changed + 2020-10-16 21:20:37Z [test1-st.external01-subnet]: CREATE_IN_PROGRESS state changed + 2020-10-16 21:20:38Z [test1-st.external01-subnet]: CREATE_COMPLETE state changed + 2020-10-16 21:20:38Z [test1-st]: CREATE_COMPLETE Stack CREATE completed successfully + + +#. Confirm the configuration. + + #. List network segments. + + .. code-block:: none + + ~(keystone_admin)]$ openstack network segment list + +--------------------------------------+--------------------------------------------+--------------------------------------+--------------+---------+ + | ID | Name | Network | Network Type | Segment | + +--------------------------------------+--------------------------------------------+--------------------------------------+--------------+---------+ + | 502e3f4f-6187-4737-b1f5-1be7fd3fc45e | test1-st-segement01-mx6fa5eonzrr | 6bbd3e4e-9419-49c6-a68a-ed51fbc1cab7 | vlan | 2111 | + | faf63edf-63f0-4e9b-b930-5fa8f43b5484 | None | 865b9576-1815-4734-a7e4-c2d0dd31d19c | vlan | 2001 | + +--------------------------------------+--------------------------------------------+--------------------------------------+--------------+---------+ + + #. List subnets. + + .. code-block:: none + + ~(keystone_admin)]$ openstack subnet list + +------------...----+---------------------+---------------...-----+------------------+ + | ID ... | Name | Network ... | Subnet | + +------------...----+---------------------+---------------...-----+------------------+ + | 0f64c277-82...f2f | external01-subnet | 6bbd3e4e-9419-...cab7 | 10.10.10.0/24 | + | bb9848b6-4b...ddc | subnet-temp | 865b9576-1815-...d19c | 192.168.17.0/24 | + +------------...----+---------------------+-----------------------+------------------+ + + In this example, the subnet external01-subnet uses a dedicated segment ID. + + #. Listing details for the subnet shows that it uses the segment ID created earlier. + + .. code-block:: none + + ~(keystone_admin)]$ openstack subnet show 0f64c277-82d7-4161-aa47-fc4cfadacf2f + + The output from this command is a row from ascii table output, it + displays the following: + + .. code-block:: none + + |grep segment | segment_id | 502e3f4f-6187-4737-b1f5-1be7fd3fc45e | + + .. note:: + Dedicated segment IDs should not be in the range created using the + :command:`openstack network segment range create` commands. This can + cause conflict errors. \ No newline at end of file diff --git a/doc/source/system_configuration/branding-the-login-banner-during-commissioning.rst b/doc/source/system_configuration/branding-the-login-banner-during-commissioning.rst new file mode 100644 index 000000000..a7e2e275b --- /dev/null +++ b/doc/source/system_configuration/branding-the-login-banner-during-commissioning.rst @@ -0,0 +1,78 @@ + +.. xjc1559744910969 +.. _branding-the-login-banner-during-commissioning: + +=========================================== +Brand the Login Banner During Commissioning +=========================================== + +You can customize the pre-login message \(issue\) and post-login |MOTD| across +the entire |prod| cluster during system commissioning and installation. + +The following files can be customized to use this feature: + +.. _branding-the-login-banner-during-commissioning-d665e16: + +.. table:: + :widths: auto + + +---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + | /etc/issue | console login banner | + +---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + | /etc/issue.net | ssh login banner | + +---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + | /etc/motd.head | message of the day header | + +---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + | /etc/motd.tail | message of the day footer | + | | | + | | This file is not present by default. You must first create it to apply your customizations. | + +---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + +issue and issue.net are free standing files. /etc/motd is generated +from the following sources in the order presented: + +.. _branding-the-login-banner-during-commissioning-d665e97: + +#. /etc/motd.head + +#. /etc/sysinv/motd.system + +#. /etc/platform/motd.license + +#. /etc/motd.tail + +Complete the following procedure to customize the login banner during +installation and commissioning: + +.. rubric:: |proc| + +#. Provide customization files. + + To customize any of the four customizable banner files listed above, + provide the new files in the following locations: + + - /opt/banner/issue + + - /opt/banner/issue.net + + - /opt/banner/motd.head + + - /opt/banner/motd.tail + + See the :command:`issue` and :command:`motd` man pages for details on + file syntax. + +#. Run Ansible Bootstrap playbook. + + When Ansible Bootstrap playbook is run, these files are moved from + /opt/banner to configuration storage and are applied to the controller + node as it is initialized. All nodes in the cluster which are + subsequently configured will retrieve these custom banners as well. + + .. note:: + In the event that an error is reported for the banner customization, + it can be repeated after running Ansible Bootstrap playbook and + system deployment. Customization errors do not impact Ansible + Bootstrap playbook. + See :ref:`Brand the Login Banner on a Commissioned System ` + for more information. \ No newline at end of file diff --git a/doc/source/system_configuration/branding-the-login-banner-on-a-commissioned-system.rst b/doc/source/system_configuration/branding-the-login-banner-on-a-commissioned-system.rst new file mode 100644 index 000000000..46186d77c --- /dev/null +++ b/doc/source/system_configuration/branding-the-login-banner-on-a-commissioned-system.rst @@ -0,0 +1,107 @@ + +.. oth1559748376782 +.. _branding-the-login-banner-on-a-commissioned-system: + +=============================================== +Brand the Login Banner on a Commissioned System +=============================================== + +You can customize the pre-login message \(issue\) and post-login +|MOTD| on an installed and commissioned |prod| cluster, simplifying propagation +of the customized files. + +.. rubric:: |context| + +The following files can be customized to use this feature: + +.. _branding-the-login-banner-on-a-commissioned-system-d665e16: + +.. table:: + :widths: auto + + +---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + | /etc/issue | console login banner | + +---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + | /etc/issue.net | ssh login banner | + +---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + | /etc/motd.head | message of the day header | + +---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + | /etc/motd.tail | message of the day footer | + | | | + | | This file is not present by default. You must first create it to apply your customizations. | + +---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + +issue and issue.net are free standing files. /etc/motd is generated from the +following sources in the order presented: + +.. _branding-the-login-banner-on-a-commissioned-system-d665e97: + +#. /etc/motd.head + +#. /etc/sysinv/motd.system + +#. /etc/platform/motd.license + +#. /etc/motd.tail + + +Complete the following procedure to customize the login banner on a +commissioned system: + +.. rubric:: |proc| + +#. Log in to the active controller. + +#. Switch to root user. + + .. code-block:: none + + $ sudo bash + # + +#. Provide any of the customized banner files in a directory of your + choosing. This example uses /opt/banner: + + - /opt/banner/issue + + - /opt/banner/issue.net + + - /opt/banner/motd.head + + - /opt/banner/motd.tail + + See the :command:`issue` and :command:`motd` man pages for details on file + syntax. + +#. Apply the customization using :command:`apply\_banner\_customization`. + + .. code-block:: none + + # apply_banner_customization + + For example: + + .. code-block:: none + + # apply_banner_customization /opt/banner + + The default path, if no parameter is specified, is the current working + directory. + + The banners are applied to the configuration and installed on the current + node, active controller. + +#. Lock and unlock other nodes in the cluster, either from the CLI or the + GUI, to install the customization on each node. + + For example: + + .. code-block:: none + + ~(keystone_admin)$ system host-lock worker-0 + ~(keystone_admin)$ system host-unlock worker-0 + +.. rubric:: |result| + +All subsequently added nodes will automatically inherit the banner +customizations. \ No newline at end of file diff --git a/doc/source/system_configuration/changing-the-mtu-of-an-oam-interface-using-horizon.rst b/doc/source/system_configuration/changing-the-mtu-of-an-oam-interface-using-horizon.rst new file mode 100644 index 000000000..c3325c954 --- /dev/null +++ b/doc/source/system_configuration/changing-the-mtu-of-an-oam-interface-using-horizon.rst @@ -0,0 +1,52 @@ + +.. paa1552672791171 +.. _changing-the-mtu-of-an-oam-interface-using-horizon: + +================================================ +Change the MTU of an OAM Interface Using Horizon +================================================ + +You can change the |MTU| value of an |OAM| interface from the Horizon Web +interface. + +If you prefer, you can use the CLI. See :ref:`Change the MTU of an OAM Interface Using the CLI `. + +Controller configuration changes require each controller to be +locked. This requires a swact during the procedure. + +.. rubric:: |proc| + +#. Lock the standby controller. + + #. From **Admin** \> **Platform** \> **Host Inventory**, select + the **Hosts** tab. + + #. From the **Edit** menu for the standby controller, select **Lock Host**. + + .. figure:: figures/rst1442611298701.png + :scale: 100% + +#. Edit the |OAM| interface to change the |MTU| value. + + #. Click the name of the standby controller, then select + the **Interfaces** tab and click **Edit** for the |OAM| interface. + + #. In the Edit Interface dialog, edit the **MTU** field, and then + click **Save**. + +#. Unlock the standby controller. + + From the **Edit** menu for the standby controller, select **Unlock Host**. + +#. Swact the hosts. + + From the **Edit** menu for the active controller, select **Swact Host**. + + .. figure:: figures/psa1420751608971.png + :scale: 100% + +#. Lock the new standby controller. + +#. Modify the |MTU| of the |OAM| interface on the new standby controller. + +#. Unlock the standby controller. \ No newline at end of file diff --git a/doc/source/system_configuration/changing-the-mtu-of-an-oam-interface-using-the-cli.rst b/doc/source/system_configuration/changing-the-mtu-of-an-oam-interface-using-the-cli.rst new file mode 100644 index 000000000..ad2244e50 --- /dev/null +++ b/doc/source/system_configuration/changing-the-mtu-of-an-oam-interface-using-the-cli.rst @@ -0,0 +1,62 @@ + +.. nnm1552672805879 +.. _changing-the-mtu-of-an-oam-interface-using-the-cli: + +================================================ +Change the MTU of an OAM Interface Using the CLI +================================================ + +You can change the |MTU| value of an |OAM| interface using the CLI. + +If you prefer, you can use the Horizon Web interface; see +:ref:`Change the MTU of an OAM Interface Using Horizon +`. + +Controller configuration changes require each controller to be locked. This +requires a swact. + +.. rubric:: |proc| + +#. Lock the standby controller. + + .. code-block:: none + + ~(keystone_admin)$ system host-lock controller-1 + +#. Use the :command:`system host-if-modify` command to specify the interface + and the new MTU value on the standby controller. This example assumes the + |OAM| interface name as **oam0**. + + .. code-block:: none + + ~(keystone_admin)$ system host-if-modify controller-1 oam0 --imtu 1600 + +#. Unlock the standby controller. + + .. code-block:: none + + ~(keystone_admin)$ system host-unlock controller-1 + +#. Swact the controllers. + + .. code-block:: none + + ~(keystone_admin)$ system host-swact controller-1 + +#. Lock the new standby controller. + + .. code-block:: none + + ~(keystone_admin)$ system host-lock controller-0 + +#. Modify the |MTU| of the corresponding interface on the standby controller. + + .. code-block:: none + + ~(keystone_admin)$ system host-if-modify controller-0 oam0 --imtu 1600 + +#. Unlock the standby controller. + + .. code-block:: none + + ~(keystone_admin)$ system host-unlock controller-0 \ No newline at end of file diff --git a/doc/source/system_configuration/changing-the-oam-ip-configuration-using-horizon.rst b/doc/source/system_configuration/changing-the-oam-ip-configuration-using-horizon.rst new file mode 100644 index 000000000..5df5fe6bf --- /dev/null +++ b/doc/source/system_configuration/changing-the-oam-ip-configuration-using-horizon.rst @@ -0,0 +1,121 @@ + +.. bmj1552672912979 +.. _changing-the-oam-ip-configuration-using-horizon: + +============================================= +Change the OAM IP Configuration Using Horizon +============================================= + +You can change the External |OAM| subnet, floating IP address, controller +addresses, and default gateway at any time after installation. + +During installation, |prod| is configured with an O|AM network subnet and +related IP addresses. You can change these addresses using the Horizon Web +interface or the CLI. You can use IPv4 or IPv6 addresses. + +.. caution:: + Access to the |OAM| network is interrupted during this procedure. When a + swact is performed on the controllers, the newly active controller uses + the changed |OAM| IP addresses. The existing |OAM| IP addresses are no + longer valid, and you must use the new |OAM| IP addresses to reconnect to + the controller. Changes to external |OAM| access routing settings may also + be required. In addition, |VNC| console access to worker-node hosts is + interrupted until the hosts are locked and unlocked. + +.. rubric:: |prereq| + +Before changing the |OAM| IP configuration, review the Fault Management page +and ensure that any existing system alarms are cleared. + +.. rubric:: |proc| + +.. _changing-the-oam-ip-configuration-using-horizon-steps-xfh-24z-5p: + +#. In the |prod| Horizon, open the System Configuration page. + + The System Configuration page is available + from **Admin** \> **Platform** \> **System Configuration** in the + left-hand pane. + +#. Select the OAM IP tab. + + The |OAM| IP page appears, showing the currently defined |OAM| network + configuration. + + .. figure:: figures/jow1413850481192.png + :scale: 100% + +#. Click **Edit OAM IP**. + + The Edit OAM IP dialog box appears. + + .. figure:: figures/jow1413850497887.png + :scale: 100% + +#. Replace the IP Subnet and/or IP addresses with different ones as required. + + .. note:: + If you change the IP address version \(IPv4 or IPv6\), ensure that the + same version is used for the DNS servers + \(see :ref:`Specify DNS Servers Using Horizon `\) + and NTP servers \(see :ref:`Configure NTP Servers and Services Using Horizon `\). + +#. Click **Save**. + + This saves the configuration change and raises + **Config out-of-date** alarms on the controller and worker nodes. + +#. Lock and unlock the standby controller to apply the configuration change. + + + #. Open the Host Inventory page, available + from **Admin** \> **Platform** \> **Host Inventory** in the left-hand + pane, and then select the **Hosts** tab. + + #. In the **Hosts** list, open the drop-down menu for the standby + controller, and then click **Lock Host**. + + The host is reported as locked. + + #. Open the drop-down menu for the standby controller, and then + click **Unlock Host**. + + #. Wait until the standby controller is reported + as **Unlocked**, **Enabled**, and **Available**. + + The **Config-out-of-date alarm** for this controller is cleared. + +#. Perform a swact to change the active controller. + + Open the drop-down menu for the active controller, and then + click **Swact Host**. + + Access to the Horizon Web interface is interrupted as control is + transferred, and Horizon becomes unresponsive. Both controllers now use + IP addresses on the new |OAM| subnet. To restore Horizon access, you must + connect the controllers physically to the new |OAM| subnet. + +#. Update the system switch configurations or controller interface + connections as required to place the controller |OAM| interfaces on the + new |OAM| subnet. + +#. Reconnect to Horizon using the new |OAM| floating IP address. + + The former active controller is now the standby controller. It is shown + with a **Config out-of-date** alarm. + +#. Lock and unlock the new standby controller to clear + the **Config out-of-date** alarm. + + Wait until the standby controller is reported + as **Unlocked**, **Enabled**, and **Available**. + +.. rubric:: |result| + +The worker node **Config out-of-date** alarms are cleared automatically as +the system configuration is updated. + +.. rubric:: |postreq| + +If alarms are not cleared after a few minutes, lock and unlock the worker +nodes to apply any other incomplete configuration changes. \ No newline at end of file diff --git a/doc/source/system_configuration/changing-the-oam-ip-configuration-using-the-cli.rst b/doc/source/system_configuration/changing-the-oam-ip-configuration-using-the-cli.rst new file mode 100644 index 000000000..b2996e66a --- /dev/null +++ b/doc/source/system_configuration/changing-the-oam-ip-configuration-using-the-cli.rst @@ -0,0 +1,70 @@ + +.. jpu1552672927783 +.. _changing-the-oam-ip-configuration-using-the-cli: + +============================================= +Change the OAM IP Configuration Using the CLI +============================================= + +If you prefer, you can use the CLI to view or change the |OAM| IP Configuration. + +To view the existing |OAM| IP configuration, use the following command. + +.. code-block:: none + + ~(keystone_admin)$ system oam-show + +-----------------+--------------------------------------+ + | Property | Value | + +-----------------+--------------------------------------+ + | created_at | 2018-05-16T20:06:25.523495+00:00 | + | isystem_uuid | b0380a56-697c-42f7-97bc-f1e407111416 | + | oam_c0_ip | 10.10.10.3 | + | oam_c1_ip | 10.10.10.4 | + | oam_floating_ip | 10.10.10.2 | + | oam_gateway_ip | 10.10.10.1 | + | oam_subnet | 10.10.10.0/24 | + | updated_at | None | + | uuid | 2818e7c4-f730-43bd-b33d-eaff53a92ee1 | + +-----------------+--------------------------------------+ + +To change the OAM IP subnet, floating IP address, gateway IP address, or +controller IP addresses, use the following command syntax. + +.. code-block:: none + + ~(keystone_admin)$ system oam-modify oam_subnet=/ \ + oam_gateway_ip= \ + oam_floating_ip= \ + oam_c0_ip= \ + oam_c1_ip= + +For example: + +.. code-block:: none + + ~(keystone_admin)$ system oam-modify oam_subnet=10.10.10.0/24 \ + oam_gateway_ip=10.10.10.1 \ + oam_floating_ip=10.10.10.2 \ + oam_c0_ip=10.10.10.3 \ + oam_c1_ip=10.10.10.4 + +.. note:: + On AIO Simplex systems, the + oam\_floating\_ip, oam\_c0\_ip and oam\_c0\_ip parameters are not + supported. To change the |OAM| IP address of a Simplex System, the parameter + oam\_ip must be used in combination with oam\_gateway\_ip and oam\_subnet. + + For example: + + .. code-block:: none + + ~(keystone_admin)$ system oam-modify oam_subnet=10.10.10.0/24 oam_gateway_ip=10.10.10.1 oam_ip=10.10.10.2 + +.. note:: + If you change the IP address version \(IPv4 or IPv6\), ensure that the + same version is used for the DNS and NTP servers. + +After changing the |OAM| server configuration, you must lock and unlock the +controllers. This process requires a swact on the controllers. Then you must +lock and unlock the worker nodes one at a time, ensuring that sufficient +resources are available to migrate any running instances. \ No newline at end of file diff --git a/doc/source/system_configuration/changing-the-timezone-configuration.rst b/doc/source/system_configuration/changing-the-timezone-configuration.rst new file mode 100644 index 000000000..f1dae8996 --- /dev/null +++ b/doc/source/system_configuration/changing-the-timezone-configuration.rst @@ -0,0 +1,57 @@ + +.. nur1552673269771 +.. _changing-the-timezone-configuration: + +================================= +Change the Timezone Configuration +================================= + +You can change the timezone defined for |prod| at any time after installation. + +You can use the CLI to view and change the timezone configuration. + +.. rubric:: |proc| + +- To view the existing timezone configuration, use the following command. + + .. code-block:: none + + $ system show + + +----------------------+--------------------------------------+ + | Property | Value | + --------------------------------------------------------------+ + | contact | None | + | created_at | 2019-12-09T16:08:34.271346+00:00 | + | description | None | + | https_enabled | False | + | location | None | + | name | 468f57ef-34c1-4e00-bba0-fa1b3f134b2b | + | region_name | RegionOne | + | sdn_enabled | False | + | security_feature | spectre_meltdown_v1 | + | service_project_name | services | + | software_version | 20.06 | + | system_mode | duplex | + | system_type | Standard | + | timezone | Canada/Eastern | + | updated_at | 2019-12-09T16:19:56.987581+00:00 | + | uuid | c0e35924-e139-4dfc-945d-47f9a663d710 | + | vswitch_type | none | + +----------------------+--------------------------------------+ + + +- To change the timezone, use the following command syntax: + + :command:`system modify --timezone=` + + For example: + + .. code-block:: none + + $ system modify --timezone=Asia/Hong_Kong + + Check that the timezone name you are using is installed in /usr/share/zoneinfo. + + After this command is executed, a several seconds delay is expected before + the configuration is applied to the system. \ No newline at end of file diff --git a/doc/source/system_configuration/configuring-a-live-migration-completion-timeout-in-nova.rst b/doc/source/system_configuration/configuring-a-live-migration-completion-timeout-in-nova.rst new file mode 100644 index 000000000..3be6271c9 --- /dev/null +++ b/doc/source/system_configuration/configuring-a-live-migration-completion-timeout-in-nova.rst @@ -0,0 +1,42 @@ + +.. err1590511228224 +.. _configuring-a-live-migration-completion-timeout-in-nova: + +===================================================== +Configure a Live Migration Completion Timeout in Nova +===================================================== + +You can configure how long to allow for a compute live migration to +complete before the operation is aborted. + +The following example applies a timeout of 300 seconds to all hosts. + +The same basic workflow of *creating an overrides file*, then +*using it to update helm overrides for the application*, and finally +*reapplying the application to make your changes effective* can be used +to apply other Nova overrides globally. + +.. rubric:: |proc| + +#. Create a yaml configuration file containing the configuration update. + + .. code-block:: none + + ~(keystone_admin)]$ cat << EOF > ./nova_override.yaml + conf: + nova: + libvirt: + live_migration_completion_timeout: 300 + EOF + +#. Update the Helm overrides using the new configuration file. + + .. parsed-literal:: + + ~(keystone_admin)]$ system helm-override-update --values ./nova_override.yaml |prefix|-openstack nova openstack --reuse-values + +#. Apply the changes. + + .. parsed-literal:: + + ~(keystone_admin)]$ system application-apply |prefix|-openstack \ No newline at end of file diff --git a/doc/source/system_configuration/configuring-a-pci-alias-in-nova.rst b/doc/source/system_configuration/configuring-a-pci-alias-in-nova.rst new file mode 100644 index 000000000..9f6a9d32c --- /dev/null +++ b/doc/source/system_configuration/configuring-a-pci-alias-in-nova.rst @@ -0,0 +1,98 @@ + +.. zrf1596656450198 +.. _configuring-a-pci-alias-in-nova: + +============================= +Configure a PCI Alias in Nova +============================= + +|PCI| passthrough devices are exposed to |VMs| using system-wide |PCI| alias. + +.. rubric:: |context| + +Each alias specifies |PCI| matching optional attributes: vendor\_id, product\_id, +and device\_type. + +where + +**name** + is a string identifying the |PCI| alias + +**device\_id** + is the device\_id value obtained from the device list + +**vendor\_id** + is the vendor\_id value obtained from the device list + +**device\_type** + is a string indicating the type of |PCI| device to add \(valid values are: + type-PCI, type-PF, or type-VF\) + +The following command displays the current configured |PCI| aliases: + +.. code-block:: none + + $ kubectl exec -it -n openstack \ + $(kubectl get pod --selector=application=nova,component=os-api -o name -n openstack) -- grep -e '\[pci\]' -e alias /etc/nova/nova.conf + + +By default it contains a list of general |PCI| aliases, such as: + +.. code-block:: none + + [pci] + alias = {"vendor_id": "8086", "product_id": "0435", "name": "qat-dh895xcc-pf"} + alias = {"vendor_id": "8086", "product_id": "0443", "name": "qat-dh895xcc-vf"} + alias = {"vendor_id": "8086", "product_id": "37c8", "name": "qat-c62x-pf"} + alias = {"vendor_id": "8086", "product_id": "37c9", "name": "qat-c62x-vf"} + alias = {"name": "gpu"} + +Additional |PCI| aliases may configured using a helm override for nova. + +The following example replaces the previous list of |PCI| aliases with a custom +list. + +.. rubric:: |proc| + +#. Create a yaml configuration file containing the configuration update. + + .. code-block:: none + + ~(keystone_admin)]$ cat << EOF > ./gpu_override.yaml + conf: + nova: + pci: + alias: + type: multistring + values: + - '{"vendor_id": "8086", "product_id": "0435", "name": + "qat-dh895xcc-pf"}' + - '{"vendor_id": "8086", "product_id": "0443", "name": + "qat-dh895xcc-vf"}' + - '{"vendor_id": "8086", "product_id": "37c8", "name": + "qat-c62x-pf"}' + - '{"vendor_id": "8086", "product_id": "37c9", "name": + "qat-c62x-vf"}' + - '{"name": "gpu"}' + - '{"vendor_id": "102b", "product_id": "0522", "name": + "matrox-g200e"}' + - '{"vendor_id": "10de", "product_id": "13f2", "name": + "nvidia-tesla-m60"}' + - '{"vendor_id": "10de", "product_id": "1b38", "name": + "nvidia-tesla-p40"}' + - '{"vendor_id": "10de", "product_id": "1eb8", + "device_type": + "type-PF", "name": "nvidia-tesla-t4-pf"}' + EOF + +#. Update the Helm overrides using the new configuration file. + + .. parsed-literal:: + + ~(keystone_admin)]$ system helm-override-update --values ./gpu_override.yaml |prefix|-openstack nova openstack --reuse-values + +#. Apply the changes. + + .. parsed-literal:: + + ~(keystone_admin)]$ system application-apply |prefix|-openstack \ No newline at end of file diff --git a/doc/source/system_configuration/configuring-ntp-servers-and-services-using-horizon.rst b/doc/source/system_configuration/configuring-ntp-servers-and-services-using-horizon.rst new file mode 100644 index 000000000..ae5006889 --- /dev/null +++ b/doc/source/system_configuration/configuring-ntp-servers-and-services-using-horizon.rst @@ -0,0 +1,110 @@ + +.. jkm1552673113419 +.. _configuring-ntp-servers-and-services-using-horizon: + +================================================ +Configure NTP Servers and Services Using Horizon +================================================ + +You can add or update a list of external NTP servers for |prod| to use for +time and clock synchronization at any time after installation, using the +Horizon Web interface. + +**NTP Service** + +.. xbooklink For more information on configuring the NTP service for clock + synchronization, see |node-doc|: `Host Inventory `. + +.. note:: + |NTP| and |PTP| are configured per host. The default is |NTP|. + + Lock/unlock the host when updating **clock\_synchronization** for the host. + +**NTP Servers** + +You can specify up to three |NTP| servers using Horizon or the CLI. + +.. note:: + When you change the |NTP|/|PTP| system configuration you have to lock/unlock + all hosts. This process requires a swact on the controllers. During a + host swact the system may raise |NTP| alarms. + +.. rubric:: |prereq| + +Before making changes to the list of |NTP| servers, review the Fault Management +page and ensure that any existing system alarms are cleared. + +.. caution:: + Before you can use fully qualified domain names \(FQDN\) instead of IPv4 + addresses, at least one valid DNS server is required. To add one, see + :ref:`Specify DNS Servers Using Horizon `. + +.. rubric:: |proc| + + +.. _configuring-ntp-servers-and-services-using-horizon-steps-xfh-24z-5p: + +#. In the |prod| Horizon, open the System Configuration page. + + The System Configuration page is available + from **Admin** \> **Platform** \> **System Configuration** in the left-hand pane. + +#. Select the NTP tab. + + The NTP page appears, showing the currently defined |NTP| servers. + + .. figure:: figures/jow1413850406811.png + :scale: 100% + +#. Click **Edit NTP**. + +#. Add or edit the IP addresses or domain names, and then click **Save**. + +#. Click **Save**. + + This raises **250.001 Configuration out-of-date** alarms against the + controllers, workers, and storages nodes. You can view the alarms on the + Fault Management page. + +#. Lock and unlock the controllers, workers, and storage nodes to apply the + configuration and clear the **Configuration out-of-date** alarms. + + Open the Host Inventory page, available + from **Admin** \> **Platform** \> **Host Inventory** in the left-hand + pane, and then select the **Hosts** tab. Hosts requiring attention are + shown with the status **Config out-of-date**. + + To lock or unlock a host, click the **Action Menu** down arrow for the + host and then use the menu selections. + + + #. Lock the standby controller. + + Wait for the lock operation to be completed. + + #. Unlock the standby controller. + + Wait for the host to become available. Its configuration is + updated, and its error message is cleared. + + #. Perform a swact on the active controller. + + Click **Action Menu \(down arrow\)** \> **Swact Host** \> for + the active controller. + + Horizon Web interface access is interrupted, and the |prod| login + screen appears. Wait briefly for the Web service to stabilize, and + then log in again. + + #. Lock the original controller \(now in standby mode\). + + Wait for the lock operation to be completed. + + #. Unlock the original controller. + + Wait for it to become available. Its configuration is updated, and its + error message is cleared. + + +#. Ensure that the **Configuration out-of-date** alarms are cleared for + both controllers. diff --git a/doc/source/system_configuration/configuring-ntp-servers-and-services-using-the-cli.rst b/doc/source/system_configuration/configuring-ntp-servers-and-services-using-the-cli.rst new file mode 100644 index 000000000..4c90f2750 --- /dev/null +++ b/doc/source/system_configuration/configuring-ntp-servers-and-services-using-the-cli.rst @@ -0,0 +1,160 @@ + +.. ktx1552673128591 +.. _configuring-ntp-servers-and-services-using-the-cli: + +================================================ +Configure NTP Servers and Services Using the CLI +================================================ + +You can use the CLI to add or update a list of |NTP| servers and services. + +**NTP Servers** + +You can specify up to three |NTP| servers using the CLI or the Horizon Web +interface. For more information, see :ref:`Configure NTP Servers and Services Using Horizon `. + +To view the existing |NTP| server configuration, use the following command. + +.. code-block:: none + + ~(keystone_admin)$ system ntp-show + +--------------+----------------------------------------------+ + | Property | Value | + +--------------+----------------------------------------------+ + | uuid | c65d5dcd-de6c-4ff9-89a1-c385dd4c7310 | + | ntpservers | 0.pool.ntp.org,1.pool.ntp.org,3.pool.ntp.org | + | isystem_uuid | a16d7b07-1d42-41cf-b001-04bc25216a2b | + | created_at | 2019-12-07T18:31:14.242942+00:00 | + | updated_at | 2019-12-07T18:42:09.244572+00:00 | + +--------------+----------------------------------------------+ + +.. note:: + When you change the |NTP| system configuration you must lock/unlock all + hosts. This process requires a swact on the controllers. During a host + swact the system may raise |NTP| alarms. + +To change the |NTP| server IP addresses, use the following command syntax. The +ntpservers option takes a comma-delimited list of |NTP| server names. + +.. code-block:: none + + ~(keystone_admin)$ system ntp-modify \ + ntpservers= + +For example: + +.. code-block:: none + + ~(keystone_admin)$ system ntp-modify ntpservers=0.pool.ntp.org,1.pool.ntp.org,3.pool.ntp.org + +**NTP Service** + +Clock synchronization, synchronizes time across multiple systems in a +network. The default value for **clock\_synchronization** is **ntp**. + +.. xbooklink For more information on configuring the NTP service for clock + synchronization, see |node-doc|: `Host Inventory `. + +.. note:: + |NTP| and |PTP| is configured per host. Lock/unlock the host when + updating **clock\_synchronization** for the host. + +Use the following command to change the clock synchronization on the host: + +.. code-block:: none + + ~(keystone_admin)$ system host-update controller-0 clock_synchronization=ntp + +-----------------------+--------------------------------------------+ + | Property | Value | + +-----------------------+--------------------------------------------+ + | action | none | + | administrative | unlocked | + | availability | available | + | bm_ip | None | + | bm_type | None | + | bm_username | None | + | boot_device | /dev/disk/by-path/pci-0000:00:1f.2-ata-1.0 | + | capabilities | {u'stor_function': u'monitor'} | + | clock_synchronization | ntp | + | config_applied | 16dfa935-e21e-4737-90f4-1afa83a3091b | + | config_status | None | + | config_target | 16dfa935-e21e-4737-90f4-1afa83a3091b | + | console | ttyS0,115200n8 | + | created_at | 2020-02-27T15:00:07.108865+00:00 | + | hostname | controller-0 | + | id | 1 | + | install_output | text | + | install_state | None | + | install_state_info | None | + | inv_state | inventoried | + | invprovision | provisioned | + | location | {} | + | mgmt_ip | 192.168.204.3 | + | mgmt_mac | 00:00:00:00:00:00 | + | operational | enabled | + | personality | controller | + | reserved | False | + | rootfs_device | /dev/disk/by-path/pci-0000:00:1f.2-ata-1.0 | + | serialid | None | + | software_load | 20.06 | + | subfunction_avail | available | + | subfunction_oper | enabled | + | subfunctions | controller,worker | + | task | | + | tboot | false | + | ttys_dcd | None | + | updated_at | 2020-02-28T17:21:42.374847+00:00 | + | uptime | 7403 | + | uuid | cc870915-b8dd-4989-914c-7095eabe36e8 | + | vim_progress_status | services-enabled | + +-----------------------+--------------------------------------------+ + +To view the |NTP| service configuration, use the following command: + +.. code-block:: none + + ~(keystone_admin)$ system host-show controller-0 + +-----------------------+------------------------------------------------+ + | Property | Value | + +-----------------------+------------------------------------------------+ + | action | none | + | administrative | unlocked | + | availability | available | + | bm_ip | None | + | bm_type | None | + | bm_username | None | + | boot_device | /dev/disk/by-path/pci-0000:04:00.0-sas | + | |-0x5001e6754aa38000-lun-0 | + | capabilities | {u'stor_function': u'monitor', u'Personality': | + | | u'Controller-Active'} | + | clock_synchronization | ntp | + | config_applied | 590f29ad-19e2-43ee-855e-f765814e3ecd | + | config_status | Config out-of-date | + | config_target | cd18ec25-c030-4b0c-862b-c39726275743 | + | console | ttyS0,115200n8 | + | created_at | 2020-02-27T18:32:58.752361+00:00 | + | hostname | controller-0 | + | id | 1 | + | install_output | text | + | install_state | None | + | install_state_info | None | + | inv_state | inventoried | + | invprovision | provisioned | + | location | {} | + | mgmt_ip | 192.168.204.3 | + | mgmt_mac | 00:1e:67:54:aa:39 | + | operational | enabled | + | personality | controller | + | reserved | False | + | rootfs_device | /dev/disk/by-path/pci-0000:04:00.0-sas | + | | -0x5001e6754aa38000-lun-0 | + | serialid | None | + | software_load | 20.06 | + | task | | + | tboot | false | + | ttys_dcd | None | + | updated_at | 2020-02-28T15:17:06.658008+00:00 | + | uptime | 159970 | + | uuid | 92c86da2-adb7-4fb2-92fc-82759e25108d | + | vim_progress_status | services-enabled | + +-----------------------+------------------------------------------------+ diff --git a/doc/source/system_configuration/configuring-ptp-service-using-horizon.rst b/doc/source/system_configuration/configuring-ptp-service-using-horizon.rst new file mode 100644 index 000000000..af087ef57 --- /dev/null +++ b/doc/source/system_configuration/configuring-ptp-service-using-horizon.rst @@ -0,0 +1,114 @@ + +.. pzk1552673010743 +.. _configuring-ptp-service-using-horizon: + +=================================== +Configure PTP Service Using Horizon +=================================== + +The |PTP| is a protocol used to synchronize clocks in a network. You can use +the Horizon Web interface to configure these services on the host. + +|PTP| provides more accurate time synchronization than |NTP|. |NTP| typically +provides time synchronization accuracy on the order of milliseconds, while +|PTP| provides time synchronization accuracy on the order of microseconds. + +.. xbooklink For more information on configuring the PTP service for clock + synchronization, see |node-doc|: `Host Inventory `. + +A |PTP| master must be present on the |OAM| Network, broadcasting |PTP| time +messages. + +.. note:: + |NTP| and |PTP| are configured per host. Lock/unlock the host when + updating **clock\_synchronization** for the host. + +.. rubric:: |prereq| + +Review the Fault Management page and ensure that any existing system alarms +are cleared. + +.. rubric:: |proc| + +.. _configuring-ptp-service-using-horizon-steps-xfh-24z-5p: + +#. In the |prod| Horizon, open the System Configuration page. + + The System Configuration page is available + from **Admin** \> **Platform** \> **System Configuration** in the + left-hand pane. + +#. Select the |PTP| tab. + + The |PTP| page appears. + +#. Click **Edit PTP**. Update the configuration of the |PTP| service. + + - **PTP Time Stamping Mode**: Hardware time stamping is the default + option, and achieves best time syncing. + + - **PTP Network Transport**: Switch between IEEE 802.3 network + transport \(L2\) or |UDP| IPv4/v6 network transport for |PTP| + messaging. + + .. note:: + L2 is the default option. + + If you use |UDP| for |PTP| transport, each |PTP| interface must have + an IP assigned. This is enforced during host unlock, and when + switching |PTP| transport to |UDP|. + + - **PTP Delay Mechanism** + + Set the |PTP| delay mechanism, the options are: + + - E2E: default delay request-response + + - P2P: peer delay + +#. Click **Save**. + + This raises **250.001 Configuration out-of-date** alarms against the + controllers, workers, and storages nodes. You can view the alarms on + the Fault Management page. + +#. Lock and unlock the controllers, workers, and storage nodes to apply the + configuration and clear the **Configuration out-of-date** alarms. + + Open the Host Inventory page, available + from **Admin** \> **Platform** \> **Host Inventory** in the left-hand + pane, and then select the **Hosts** tab. Hosts requiring attention are + shown with the status **Config out-of-date**. + + To lock or unlock a host, click the **Action Menu** down arrow for the + host and then use the menu selections. + + #. Lock the standby controller. + + Wait for the lock operation to be completed. + + #. Unlock the standby controller. + + Wait for the host to become available. Its configuration is + updated, and its error message is cleared. + + #. Perform a swact on the active controller. + + Click **Action Menu \(down arrow\)** \> **Swact Host** \> for + the active controller. + + Horizon Web interface access is interrupted, and the |prod| login + screen appears. Wait briefly for the Web service to stabilize, and + then log in again. + + #. Lock the original controller \(now in standby mode\). + + Wait for the lock operation to be completed. + + #. Unlock the original controller. + + Wait for it to become available. Its configuration is updated, and + its error message is cleared. + +#. Ensure that the **Configuration out-of-date** alarms are cleared for + both controllers. \ No newline at end of file diff --git a/doc/source/system_configuration/configuring-ptp-service-using-the-cli.rst b/doc/source/system_configuration/configuring-ptp-service-using-the-cli.rst new file mode 100644 index 000000000..dfe0a7659 --- /dev/null +++ b/doc/source/system_configuration/configuring-ptp-service-using-the-cli.rst @@ -0,0 +1,275 @@ + +.. cyw1552673027689 +.. _configuring-ptp-service-using-the-cli: + +=================================== +Configure PTP Service Using the CLI +=================================== + +You can use the CLI to configure |PTP| services. + +.. contents:: + :local: + :depth: 1 + +For information on configuring the |PTP| service for clock synchronization +using the Horizon Web interface see +:ref:`Configure PTP Service Using Horizon +`. + +You can also specify the |PTP| service for **clock\_synchronization** using +the web administration interface. + +.. xbooklink For more information, see |node-doc|: `Host Inventory `. + +**PTP Service** + +To view the existing |PTP| status, use the following command. + +.. code-block:: none + + ~(keystone_admin)$ system ptp-show + +--------------+--------------------------------------+ + | Property | Value | + +--------------+--------------------------------------+ + | uuid | 4844eca1-13bb-471e-9162-e5f2bb97d650 | + | mode | hardware | + | transport | l2 | + | mechanism | e2e | + | isystem_uuid | a16d7b07-1d42-41cf-b001-04bc25216a2b | + | created_at | 2019-12-09T16:08:34.319374+00:00 | + | updated_at | None | + +--------------+--------------------------------------+ + +.. warning:: + |NTP| and |PTP| are mutually exclusive on a particular host; only one can be + enabled at any time. + +The default value for **clock\_synchronization** is **ntp**. Use the +following command to change the clock synchronization on the host. |NTP| +and |PTP| are configured per host. Lock/unlock the host when updating. + +.. code-block:: none + + ~(keystone_admin)$ system host-update controller-0 clock_synchronization=ptp + +-----------------------+---------------------------------------+ + | Property | Value | + +-----------------------+---------------------------------------+ + | action | none | + | administrative | unlocked | + | availability | available | + | bm_ip | None | + | bm_type | None | + | bm_username | None | + | boot_device | /dev/disk/by-path/pci-0000:04:00.0-sas| + | | -0x5001e6754aa38000-lun-0 | + | capabilities | {u'stor_function': u'monitor'} | + | clock_synchronization | ptp | + | config_applied | 590f29ad-19e2-43ee-855e-f765814e3ecd | + | config_status | None | + | config_target | 590f29ad-19e2-43ee-855e-f765814e3ecd | + | console | ttyS0,115200n8 | + | created_at | 2019-12-07T18:32:58.752361+00:00 | + | hostname | controller-0 | + | id | 1 | + | install_output | text | + | install_state | None | + | install_state_info | None | + | inv_state | inventoried | + | invprovision | provisioned | + | location | {} | + | mgmt_ip | 192.168.204.3 | + | mgmt_mac | 00:1e:67:54:aa:39 | + | operational | enabled | + | personality | controller | + | reserved | False | + | rootfs_device | /dev/disk/by-path/pci-0000:04:00.0 | + | | -sas-0x5001e6754aa38000-lun-0 | + | serialid | None | + | software_load | 20.06 | + | task | | + | tboot | false | + | ttys_dcd | None | + | updated_at | 2019-12-07T21:17:28.627489+00:00 | + | uptime | 9020 | + | uuid | 92c86da2-adb7-4fb2-92fc-82759e25108d | + | vim_progress_status | services-enabled | + +-----------------------+---------------------------------------+ + +To view the |PTP| service configuration, use the following command: + +.. code-block:: none + + ~(keystone_admin)$ system host-show controller-0 + +-----------------------+------------------------------------------------+ + | Property | Value | + +-----------------------+------------------------------------------------+ + | action | none | + | administrative | unlocked | + | availability | available | + | bm_ip | None | + | bm_type | None | + | bm_username | None | + | boot_device | /dev/disk/by-path/pci-0000:04:00.0-sas | + | |-0x5001e6754aa38000-lun-0 | + | capabilities | {u'stor_function': u'monitor', u'Personality': | + | | u'Controller-Active'} | + | clock_synchronization | ptp | + | config_applied | 590f29ad-19e2-43ee-855e-f765814e3ecd | + | config_status | Config out-of-date | + | config_target | cd18ec25-c030-4b0c-862b-c39726275743 | + | console | ttyS0,115200n8 | + | created_at | 2019-12-09T16:10:19.143372+00:00 | + | hostname | controller-0 | + | id | 1 | + | install_output | text | + | install_state | None | + | install_state_info | None | + | inv_state | inventoried | + | invprovision | provisioned | + | location | {} | + | mgmt_ip | 192.168.204.3 | + | mgmt_mac | 00:1e:67:54:aa:39 | + | operational | enabled | + | personality | controller | + | reserved | False | + | rootfs_device | /dev/disk/by-path/pci-0000:04:00.0-sas | + | | -0x5001e6754aa38000-lun-0 | + | serialid | None | + | software_load | 20.06 | + | task | | + | tboot | false | + | ttys_dcd | None | + | updated_at | 2019-12-10T14:55:58.595239+00:00 | + | uptime | 159970 | + | uuid | 92c86da2-adb7-4fb2-92fc-82759e25108d | + | vim_progress_status | services-enabled | + +-----------------------+------------------------------------------------+ + + +.. _configuring-ptp-service-using-the-cli-ul-srp-rnn-3jb: + +- **PTP Time Stamping Mode**: |NTP| and |PTP| are configured per host. + Lock/unlock the host when Hardware time stamping is the default + option, and achieves best time synching. Use the following command: + + .. code-block:: none + + ~(keystone_admin)$ system ptp-modify --mode= + +- **PTP Network Transport**: Switch between IEEE 802.3 network + transport \(L2\) or |UDP| IPv4/v6 network transport for |PTP| + messaging. Use the following command: + + .. code-block:: none + + ~(keystone_admin)$ system ptp-modify --transport= + + .. note:: + L2 is the default option. + + If you use |UDP| for |PTP| transport, each |PTP| interface must have an + IP assigned. This is enforced during host unlock, and when switching + |PTP| transport to |UDP|. + +- **PTP Delay Mechanism** + + Set the |PTP| delay mechanism, the options are: + + - E2E: default delay request-response + + - P2P: peer delay + + Use the following command: + + .. code-block:: none + + ~(keystone_admin)$ system ptp-modify --mechanism= + +- **PTP Role** + + |PTP| master/slave interfaces are not defined by default. They must be + specified by the administrator for each host. + + The **ptp\_role** option can be added to interfaces, and can be defined + for master, slave, and none. This option allows administrators to + configure interfaces that can be used for |PTP| services. The master and + slave roles are limited to platform, |SRIOV|, and VF interfaces. Any number + of master and slave interfaces can be specified per host. + + If a host has **clock\_synchronization=ptp**, there must be at least one + host interface with a |PTP| role specified. This is enforced during host + unlock. + + For example, this service can be specified using the following commands: + + .. code-block:: none + + ~(keystone_admin)$ system host-if-modify compute-3 ens803f0 -n sriovptp --ptp-role slave + +To apply changes to hosts, use the following command: + +.. code-block:: none + + ~(keystone_admin)$ system ptp-apply + +|PTP| changes will be applied to all unlocked hosts configured with ptp +clock\_synchronization. + +.. _configuring-ptp-service-using-the-cli-section-qn1-p3d-vkb: + +---------------------- +Advanced Configuration +---------------------- + +Using service parameters, you can customize a wide range of linuxptp module +settings to use the system in a much wider range of |PTP| configurations. + +.. caution:: + These parameters are written to the ptp4l configuration file without error + checking. Caution must be taken to ensure that parameter names and + values are correct as errors will cause ptp4l launch failures. + +The following service parameters are available: + +**ptp global =** + This service parameter allows you to write or overwrite values found + in the global section of the ptp4l configuration file. For example, + the command + + .. code-block:: none + + ~(keystone_admin)$ system service-parameter-add ptp global domainNumber=24 + + results in the following being written to the configuration file: + + .. code-block:: none + + domainNumber 24 + + ptp global service parameters take precedence over the system ptp + values. For example, if the system ptp delay mechanism is + **E2E**, and you subsequently run the command + + .. code-block:: none + + ~(keystone_admin)$ system service-parameter-add ptp global delay_mechanism=P2P + + Then the **P2P** will be used instead. + +**ptp phc2sys update-rate=** + This parameter controls the update-rate of the phc2sys service, in + seconds. + +**ptp phc2sys summary-updates=** + This parameter controls the number of clock updates to be included in + summary statistics. + +To apply service parameter changes to hosts, use the following command: + +.. code-block:: none + + ~(keystone_admin)$ system service-parameter-apply ptp + +|PTP| changes will be applied to all unlocked hosts configured with +ptp clock\_synchronization. \ No newline at end of file diff --git a/doc/source/system_configuration/configuring-the-rpc-response-timeout-in-cinder.rst b/doc/source/system_configuration/configuring-the-rpc-response-timeout-in-cinder.rst new file mode 100644 index 000000000..cd3889b2f --- /dev/null +++ b/doc/source/system_configuration/configuring-the-rpc-response-timeout-in-cinder.rst @@ -0,0 +1,41 @@ + +.. apa1590511404706 +.. _configuring-the-rpc-response-timeout-in-cinder: + +============================================ +Configure the RPC Response Timeout in Cinder +============================================ + +You can change the Cinder |RPC| response timeout for all hosts using a helm +override. + +.. rubric:: |proc| + +#. Create the Cinder overrides files. + + .. code-block:: none + + ~(keystone_admin)]$ cat < ~/cinder-overrides.yaml + conf: + cinder: + DEFAULT: + rpc_response_timeout: 30 + EOF + +#. Update the Cinder overrides. + + .. parsed-literal:: + + ~(keystone_admin)]$ system helm-override-update --values /home/sysadmin/cinder-overrides.yaml |prefix|-openstack cinder openstack --reuse-values + +#. Update |prefix|-openstack to apply the update. + + .. parsed-literal:: + + ~(keystone_admin)]$ system application-apply |prefix|-openstack + +#. Confirm that the update has applied successfully. + + .. code-block:: none + + ~(keystone_admin)]$ kubectl exec -n openstack -- grep rpc_response_timeout /etc/cinder/cinder.conf \ No newline at end of file diff --git a/doc/source/system_configuration/console-keyboard-mapping.rst b/doc/source/system_configuration/console-keyboard-mapping.rst new file mode 100644 index 000000000..e81ce230d --- /dev/null +++ b/doc/source/system_configuration/console-keyboard-mapping.rst @@ -0,0 +1,57 @@ + +.. rws1552674043508 +.. _console-keyboard-mapping: + +======================== +Console Keyboard Mapping +======================== + +You can change the keyboard layout settings used on the text console for +a |prod| node. + +You can log in to the console using the US keyboard layout and then change +the keyboard settings, if required. Use the following CLI commands to change +the keyboard layout settings on your keyboard: + +To display the current console keyboard settings that are configured for the +virtual console: + +.. code-block:: none + + $ localectl status + +For example, + +.. code-block:: none + + System Locale:LANG=en_US.UTF-8 + VC Keymap:us + X11 Layout:n/a + +To check if a keyboard layout can be configured on your system, for example: + +.. code-block:: none + + $ localectl list-keymaps|fgrep 106 + jp 106 + +To set the console keyboard layout, use the following syntax: + +.. code-block:: none + + $ sudo localectl set-keymap + +For example, to use jp106: + +.. code-block:: none + + $ sudo localectl set-keycap jp106 + +.. code-block:: none + + $ localectl status + System Locale:LANG=en_US.UTF-8 + VC Keymap:jp106 + X11 Layout:jp + X11 Model:jp106 + X11 Options:terminate:ctrl_alt_bksp \ No newline at end of file diff --git a/doc/source/system_configuration/converting-a-duplex-system-to-direct-connection.rst b/doc/source/system_configuration/converting-a-duplex-system-to-direct-connection.rst new file mode 100644 index 000000000..856c5b558 --- /dev/null +++ b/doc/source/system_configuration/converting-a-duplex-system-to-direct-connection.rst @@ -0,0 +1,58 @@ + +.. uyd1552672677585 +.. _converting-a-duplex-system-to-direct-connection: + +============================================ +Convert a Duplex System to Direct Connection +============================================ + +On a |prod| |AIO| system configured to use switch-based network connection for +the management and cluster host networks, you can convert to direct +\(peer-to-peer\) connection. + +The connection type is initially configured at installation. You can change +it at any time. You must use the CLI to make the change. + +.. xbooklinkFor more about the available connection modes, + see |planning-doc|: `Networks for a Duplex System `. + +.. rubric:: |proc| + +#. Use the :command:`system modify` command to specify direct + connection \(**duplex-direct**\). + + .. code-block:: none + + ~(keystone_admin)$ system modify --system_mode=duplex-direct + + This raises **Config-out-of-date** alarm messages on both controllers. + +#. Lock and then unlock the standby controller to update its configuration. + + Wait for the controller to be reported as **Unlocked**, **Available**, + and **Online**, and its **Config-out-of-date** alarm message to be + cleared. + +#. Swact the controllers. + +#. Lock the new standby controller. + +#. Disconnect the management and infrastructure cables from the |ToR| switch. + + This raises **Port failed** and **Interface failed** alarms on the + active controller for the management and infrastructure interfaces. + +#. Reconnect the cables in a peer-to-peer configuration. + + Wait for the network interface alarms to be cleared. + +#. Unlock the standby controller to update its configuration. + + Wait for the controller to be reported as **Unlocked**, **Available**, + and **Online**, and its **Config-out-of-date** alarm message to be + cleared. + +.. rubric:: |result| + +The system is now reconfigured to use direct connections for the internal +networks. diff --git a/doc/source/system_configuration/converting-a-duplex-system-to-switch-based-connection.rst b/doc/source/system_configuration/converting-a-duplex-system-to-switch-based-connection.rst new file mode 100644 index 000000000..ca551fa25 --- /dev/null +++ b/doc/source/system_configuration/converting-a-duplex-system-to-switch-based-connection.rst @@ -0,0 +1,74 @@ + +.. egs1552672694354 +.. _converting-a-duplex-system-to-switch-based-connection: + +================================================== +Convert a Duplex System to Switch-Based Connection +================================================== + +On a |prod| |AIO| Duplex system configured to use direct connections for +the management and cluster host networks, you can convert to switch-based +connections. + +The connection type is initially configured at installation. You can change +it at any time. You must use the CLI to make the change. + +.. xbooklink For more about the available connection modes, + see |planning-doc|: `Networks for a Duplex System `. + +.. rubric:: |prereq| + +Extra network cables are required to connect both controllers to the |ToR| +switch. + +The |ToR| switch must be configured correctly for communication with the +controllers. + +.. rubric:: |proc| + +#. Use the :command:`system modify` command to specify switch-based + connection \(**duplex**\). + + .. code-block:: none + + ~(keystone_admin)$ system modify --system_mode=duplex + + + This raises **Config-out-of-date** alarm messages on both controllers. + +#. Lock the standby controller. + +#. Disconnect the management and infrastructure cables from the standby + controller. + + This raises **Port failed** and **Interface failed** alarms on the active + controller for the management and infrastructure interfaces. + +#. Connect both controllers to the |ToR| switch. + + Connect the existing cables from the active controller to the |ToR| switch. + Use additional cables to connect the standby controller to the |ToR| + switch. + + Wait for the network interface alarms on the active controller to be + cleared. + +#. Unlock the standby controller to update its configuration. + + Wait for the controller to be reported as **Unlocked**, **Available**, + and **Online**, and for its **Config-out-of-date** alarm message to be + cleared. + +#. Swact the controllers. + +#. Lock and then unlock the new standby controller to update its + configuration. + + Wait for the controller to be reported as **Unlocked**, **Available**, + and **Online**, and for its **Config-out-of-date** alarm message to be + cleared. + +.. rubric:: |result| + +The system is now reconfigured to use switch-based connections for the +internal networks. \ No newline at end of file diff --git a/doc/source/system_configuration/creating-a-custom-branding-tarball.rst b/doc/source/system_configuration/creating-a-custom-branding-tarball.rst new file mode 100644 index 000000000..b5d9a9805 --- /dev/null +++ b/doc/source/system_configuration/creating-a-custom-branding-tarball.rst @@ -0,0 +1,130 @@ + +.. ngt1557520137257 +.. _creating-a-custom-branding-tarball: + +================================ +Create a Custom Branding Tarball +================================ + +This section contains instructions and examples for creating and applying a +tarball containing a custom Horizon Web interface theme, and associated +branding files, for the |prod|. + +You can modify the existing style sheet, font, and image files to develop +your own branding, package it, and then apply the branding by installing the +tarball that includes the modified files along with a manifest. To create a +custom branding tarball, with a new custom theme, and package it, follow the +steps below: + +.. rubric:: |proc| + +#. You can use the existing default Horizon theme as a starting point for the + creation of your custom theme or for the directory structure. + +#. Customize the styles and color scheme using the **\_styles.scss**, + and **\_variables.scss** files. Image overrides can be placed in the + **static/img/** folder, and template overrides can be placed in the + **templates** folder. This theme can be found in the Horizon repository, + at `GitHub `__ + or on a controller host, at /usr/share/openstack-dashboard/openstack\_dashboard/themes/default/. + +#. Copy the theme and modify it to fit your requirements. + + For more information on customizing your theme, see the OpenStack + documentation at, `https://docs.openstack.org/horizon/latest/configuration/branding.html `__ + + .. note:: + + - You can use the **example** theme as a guide to where + customized templates and javascript must be located in a custom + theme, and can be found next to the default theme. + + - The name of the custom theme is **custom** and must be used in the + source paths of new images or javascript, for example, + **/static/themes/custom/img/extra\_img.png**. + + - If a static folder is used, the **\_styles.scss**, and + **\_variables.scss** files must be located in the static folder + and not in the root of the theme. + +#. You must add a **manifest.py** file to your theme directory that is used + to overwrite Horizon's branding-related settings. This file should + specify the following information: + + .. code-block:: none + + # SITE_BRANDING = "Sample System Name" + + where + **Sample System Name** is the name that will be used in the site title + + .. code-block:: none + + # HORIZON_CONFIG["help_url"] = "https://www.openstack.org/" + + where + the **help\_url** is the help link for users. + + The theme directory should have the following files, depending on how + extensive the theme is. Use the following command to find the files: + + .. code-block:: none + + # find . + ./manifest.py + ./static + ./static/img + ./static/img/logo-splash.svg + ./static/img/logo.svg + ./static/_styles.scss + ./static/_variables.scss + ./templates + ./templates/auth + ./templates/auth/login.html + ./templates/auth/_login_form.html + ./templates/base.html + +#. Compress this directory into a tarball that can then be deployed in + running systems. + + .. note:: + This tarball must have the extension **.tgz**. There are no + limitations on the name of this file. + + .. code-block:: none + + # ls manifest.py static templates + + .. code-block:: none + + # tar czfv new_branding.tgz * + manifest.py + static/ + static/img/ + static/img/favicon.png + static/img/logo-splash.svg + static/img/logo.png + static/img/logo.svg + static/_styles.scss + static/_variables.scss + templates/ + templates/auth/ + templates/auth/login.html + templates/auth/_login_form.html + templates/base.html + +.. rubric:: |postreq| + +After creating your custom branding tarball containing a customized Horizon Web +interface theme and associated branding files, you cqn apply it to both newly +installed and running systems. You can apply it to different stages in your +installation. + +For more information on applying the tarball to newly installed systems prior +to running the bootstrap playbook, +see :ref:`Apply a Custom Branding Tarball to Newly Installed Systems +`. + +For more information on applying the tarball to running systems, +see :ref:`Apply a Custom Branding Tarball to Running Systems +`. \ No newline at end of file diff --git a/doc/source/system_configuration/creating-optional-telemetry-services.rst b/doc/source/system_configuration/creating-optional-telemetry-services.rst new file mode 100644 index 000000000..9ee91d4e3 --- /dev/null +++ b/doc/source/system_configuration/creating-optional-telemetry-services.rst @@ -0,0 +1,149 @@ + +.. swo1591098193543 +.. _creating-optional-telemetry-services: + +================================== +Enable Optional Telemetry Services +================================== + +By default in |prod-os|, Telemetry services are disabled. These +services are optional and includes Ceilometer \(Data collection service\), +Panko \(Event storage service\), Gnocchi +\(Time series metric storage service\), and Aodh \(Alarming service\). + +You can use the following procedure to enable these optional telemetry +services on the active controller. + +.. rubric:: |proc| + +#. To enable telemetry services, use the following command: + + .. code-block:: none + + $ system help helm-chart-attribute-modify + + Usage: system helm-chart-attribute-modify + [--enabled ] + + + Modify helm chart attributes. This function is provided to modify system + behavioral attributes related to a chart. This does not modify a chart, nor + does it modify chart overrides which are managed through the helm-override- + update command. + + Positional arguments: + Name of the application + Name of the chart + Namespace of the chart + + Optional arguments: + --enabled + Chart enabled. + + #. Run the following command to enable Ceilometer service. + + .. parsed-literal:: + + ~(keystone_admin)]$ system helm-chart-attribute-modify |prefix|-openstack ceilometer openstack --enabled true + +------------+--------------------+ + | Property | Value | + +------------+--------------------+ + | attributes | {u'enabled': True} | + | name | ceilometer | + | namespace | openstack | + +------------+--------------------+ + + #. Run the following command to enable Gnocchi service. + + .. parsed-literal:: + + ~(keystone_admin)]$ system helm-chart-attribute-modify |prefix|-openstack gnocchi openstack --enabled true + +------------+--------------------+ + | Property | Value | + +------------+--------------------+ + | attributes | {u'enabled': True} | + | name | gnocchi | + | namespace | openstack | + +------------+--------------------+ + + #. Run the following command to enable Aodh service. + + .. parsed-literal:: + + ~(keystone_admin)]$ system helm-chart-attribute-modify |prefix|-openstack aodh openstack --enabled true + +------------+--------------------+ + | Property | Value | + +------------+--------------------+ + | attributes | {u'enabled': True} | + | name | aodh | + | namespace | openstack | + +------------+--------------------+ + + #. Run the following command to enable Panko service. + + .. parsed-literal:: + + ~(keystone_admin)]$ system helm-chart-attribute-modify |prefix|-openstack panko openstack --enabled true + +------------+--------------------+ + | Property | Value | + +------------+--------------------+ + | attributes | {u'enabled': True} | + | name | panko | + | namespace | openstack | + +------------+--------------------+ + +#. Run the following command to verify that all services are enabled. + + .. parsed-literal:: + + ~(keystone_admin)]$ system helm-override-list |prefix|-openstack -l + +---------------------+--------------------------------+---------------+ + | chart name | overrides namespaces | chart enabled | + +---------------------+--------------------------------+---------------+ + | aodh | [u'openstack'] | [True] | + | barbican | [u'openstack'] | [False] | + | ceilometer | [u'openstack'] | [True] | + | ceph-rgw | [u'openstack'] | [False] | + | cinder | [u'openstack'] | [True] | + | dcdbsync | [u'openstack'] | [True] | + | fm-rest-api | [u'openstack'] | [True] | + | garbd | [u'openstack'] | [True] | + | glance | [u'openstack'] | [True] | + | gnocchi | [u'openstack'] | [True] | + | heat | [u'openstack'] | [True] | + | helm-toolkit | [] | [] | + | horizon | [u'openstack'] | [True] | + | ingress | [u'kube-system', u'openstack'] | [True, True] | + | ironic | [u'openstack'] | [False] | + | keystone | [u'openstack'] | [True] | + | keystone-api-proxy | [u'openstack'] | [True] | + | libvirt | [u'openstack'] | [True] | + | mariadb | [u'openstack'] | [True] | + | memcached | [u'openstack'] | [True] | + | networking-avs | [u'openstack'] | [True] | + | neutron | [u'openstack'] | [True] | + | nginx-ports-control | [] | [] | + | nova | [u'openstack'] | [True] | + | nova-api-proxy | [u'openstack'] | [True] | + | openvswitch | [u'openstack'] | [True] | + | panko | [u'openstack'] | [True] | + | placement | [u'openstack'] | [True] | + | rabbitmq | [u'openstack'] | [True] | + | version_check | [] | [] | + +---------------------+--------------------------------+---------------+ + +#. To reapply these changes to the |prefix|-openstack application, run + the following command. + + .. parsed-literal:: + + ~(keystone_admin)]$ system application-apply |prefix|-openstack + + Once |prefix|-openstack is applied successfully, telemetry services + will be available. + +#. Run the following helm command to verify the updates. + + .. code-block:: none + + ~(keystone_admin)]$ helm list | grep -E ceilometer|gnocchi|panko|aodh diff --git a/doc/source/system_configuration/enabling-the-qos-extension-for-neutron.rst b/doc/source/system_configuration/enabling-the-qos-extension-for-neutron.rst new file mode 100644 index 000000000..53c274864 --- /dev/null +++ b/doc/source/system_configuration/enabling-the-qos-extension-for-neutron.rst @@ -0,0 +1,53 @@ + +.. mup1591370716032 +.. _enabling-the-qos-extension-for-neutron: + +==================================== +Enable the QoS Extension for Neutron +==================================== + +You can use Helm overrides to enable the |QoS| Neutron extension. + +.. rubric:: |proc| + +#. Create a yaml file to enable the qos extension for neutron. + + .. code-block:: none + + ~(keystone_admin)]$ cat > neutron-overrides.yaml <` for instructions on setting + up the admin credentials for the containerized OpenStack application. \ No newline at end of file diff --git a/doc/source/system_configuration/enabling-the-trunk-extension-for-neutron.rst b/doc/source/system_configuration/enabling-the-trunk-extension-for-neutron.rst new file mode 100644 index 000000000..f796fad69 --- /dev/null +++ b/doc/source/system_configuration/enabling-the-trunk-extension-for-neutron.rst @@ -0,0 +1,42 @@ + +.. jvu1591371696823 +.. _enabling-the-trunk-extension-for-neutron: + +====================================== +Enable the Trunk Extension for Neutron +====================================== + +You can use Helm overrides to enable the Trunk Neutron extension. + +.. rubric:: |proc| + +#. Create a yaml file to enable the trunk extension for neutron. + + .. code-block:: none + + ~(keystone_admin)]$ cat > neutron-overrides.yaml <`__. + +Use the following command to edit the globalnetworkpolicy and modify the +|OAM| Firewall according to the above |GNP| syntax: + +.. code-block:: none + + kubectl edit globalnetworkpolicy + +.. xbooklink For more information about the |prod| firewall, + see |sec-doc|: `Firewall Options `. diff --git a/doc/source/system_configuration/resynchronizing-a-host-to-the-ntp-server.rst b/doc/source/system_configuration/resynchronizing-a-host-to-the-ntp-server.rst new file mode 100644 index 000000000..465023813 --- /dev/null +++ b/doc/source/system_configuration/resynchronizing-a-host-to-the-ntp-server.rst @@ -0,0 +1,33 @@ + +.. sod1552673143944 +.. _resynchronizing-a-host-to-the-ntp-server: + +====================================== +Resynchronize a Host to the NTP Server +====================================== + +If host synchronization is lost for any reason, you must lock and then +unlock the host to restore the synchronization safely. + +If a large time discrepancy \(greater than 1000 seconds, or about 17 +minutes\) develops between the clock time on a host and the time as reported +by an |NTP| server, the **ntpd** service on the host stops, and Alarm +200.006 \( 'ntpd' process has failed\) is logged in the Alarm Log +and the Customer Log. This can occur if the clock on the host is +inadvertently set incorrectly, or cannot access the |NTP| server for the +correct time at initialization and defaults to an incorrect time. + +.. rubric:: |proc| + +.. _resynchronizing-a-host-to-the-ntp-server-steps-rl4-xmy-hkb: + +- To recover, lock and then unlock the host. + + .. caution:: + Do not attempt to recover by restarting the **ntpd** service. This + can cause problems for other running services. + +.. rubric:: |result| + +The time is automatically synchronized to the |NTP| server when the host is +unlocked and alarm 200.006 for this host will be cleared. diff --git a/doc/source/system_configuration/specifying-dns-servers-using-horizon.rst b/doc/source/system_configuration/specifying-dns-servers-using-horizon.rst new file mode 100644 index 000000000..36e409a96 --- /dev/null +++ b/doc/source/system_configuration/specifying-dns-servers-using-horizon.rst @@ -0,0 +1,32 @@ + +.. kjm1552673210981 +.. _specifying-dns-servers-using-horizon: + +================================= +Specify DNS Servers Using Horizon +================================= + +You can add or update a list of external DNS servers for |prod| to use for +domain name resolution at any time after installation. + +You can specify up to three DNS servers using the Horizon Web interface. + +.. rubric:: |proc| + +#. In the |prod| Horizon Web interface, open the System Configuration page. + + The System Configuration page is available + from **Admin** \> **Platform** \> **System Configuration** in the + left-hand pane. + +#. Select the DNS tab. + + The DNS page appears, showing the currently defined DNS servers. + +#. Click **Edit DNS**. + +#. In the Edit DNS dialog box, add or edit the IP addresses, and then + click **Save**. + + .. figure:: figures/jow1413850386429.png + :scale: 100% \ No newline at end of file diff --git a/doc/source/system_configuration/specifying-dns-servers-using-the-cli.rst b/doc/source/system_configuration/specifying-dns-servers-using-the-cli.rst new file mode 100644 index 000000000..7fd4a4b57 --- /dev/null +++ b/doc/source/system_configuration/specifying-dns-servers-using-the-cli.rst @@ -0,0 +1,37 @@ + +.. ocy1552673225265 +.. _specifying-dns-servers-using-the-cli: + +================================= +Specify DNS Servers Using the CLI +================================= + +You can use the CLI to add or update up to three DNS servers. + +To view the existing DNS server configuration, use the following command: + +.. code-block:: none + + ~(keystone_admin)$ system dns-show + +--------------+--------------------------------------+ + | Property | Value | + +--------------+--------------------------------------+ + | uuid | cffcde8c-2124-4d19-881f-764ddafc8558 | + | nameservers | 8.8.8.8 | + | isystem_uuid | e1f955a1-2dee-492e-8c72-8b88a8b08558 | + | created_at | 2017-06-23T00:34:38.353023+00:00 | + | updated_at | 2017-06-24T20:52:13.307660+00:00 | + +--------------+--------------------------------------+ + +To change the list of DNS servers, use the following command syntax. The +nameservers option takes a comma-delimited list of IP addresses. + +.. code-block:: none + + ~(keystone_admin)$ system dns-modify nameservers= + +For example: + +.. code-block:: none + + ~(keystone_admin)$ system dns-modify nameservers=8.8.8.8,8.8.4.4 diff --git a/doc/source/system_configuration/system-config-helm-package-manager.rst b/doc/source/system_configuration/system-config-helm-package-manager.rst new file mode 100644 index 000000000..95f246c21 --- /dev/null +++ b/doc/source/system_configuration/system-config-helm-package-manager.rst @@ -0,0 +1,41 @@ + +.. emk1568230814240 +.. _system-config-helm-package-manager: + +==================== +Helm Package Manager +==================== + +|prod-long| supports Helm v2 with Tiller, the Kubernetes package manager +that can be used to manage the lifecycle of end-user hosted applications +within the Kubernetes cluster. + +Helm packages are defined by Helm charts with container information sufficient +for managing a Kubernetes application. You can configure, install, and +upgrade your Kubernetes applications using Helm charts. Helm charts are +defined with a default set of values that describe the behavior of the +service installed within the Kubernetes cluster. + +Upon system installation, the official curated helm chart repository is added +to the local helm repo list, in addition, a number of local repositories +\(containing optional |prod-long| packages\) are created and added to the +helm repo list. For more information, +see `https://github.com/helm/charts `__. + +Use the following command to list the helm repositories: + +.. parsed-literal:: + + ~(keystone_admin)$ helm repo list + NAME URL + stable https://kubernetes-charts.storage.googleapis.com + local http://127.0.0.1:8879/charts + starlingx http://127.0.0.1:8080/helm_charts/starlingx + |prefix|-platform |s| http://127.0.0.1:8080/helm_charts/|prefix|-platform + +For more information on Helm, see the documentation +at `https://helm.sh/docs/ `__. + +**Tiller** is a component of Helm. Tiller interacts directly with the +Kubernetes API server to install, upgrade, query, and remove Kubernetes +resources. diff --git a/doc/source/system_configuration/system-configuration-management-overview.rst b/doc/source/system_configuration/system-configuration-management-overview.rst new file mode 100644 index 000000000..79bafda42 --- /dev/null +++ b/doc/source/system_configuration/system-configuration-management-overview.rst @@ -0,0 +1,14 @@ + +.. ewz1552673812105 +.. _system-configuration-management-overview: + +======================================== +System Configuration Management Overview +======================================== + +|prod-long| system configuration can be done any time after installation +to change system configuration data specified during system installation, +and to set additional system configuration data. + +.. xbooklink For details on accessing the system, + see |sec-doc|: `Access the System ` \ No newline at end of file diff --git a/doc/source/system_configuration/system-configuration-overview.rst b/doc/source/system_configuration/system-configuration-overview.rst new file mode 100644 index 000000000..a3a28238f --- /dev/null +++ b/doc/source/system_configuration/system-configuration-overview.rst @@ -0,0 +1,103 @@ + +.. eqg1590091622329 +.. _system-configuration-overview: + +=========================================== +Overview of Configuring StarlingX OpenStack +=========================================== + +|prod-os| is installed and managed as an Armada application. + +See |prod| System Configuration: :ref:`Application Management +`, for a description of the application +lifecycle commands for managing an Armada application. + +Armada Applications are a set of one or more interdependent Application Helm +Charts. In the case of |prod|, there is generally a Helm Chart for every +OpenStack service. + +.. parsed-literal:: + + ~(keystone_admin)]$ system helm-override-list |prefix|-openstack + +---------------------------+--------------------------------+ + | chart name | overrides namespaces | + +---------------------------+--------------------------------+ + | aodh | [u'openstack'] | + | barbican | [u'openstack'] | + | ceilometer | [u'openstack'] | + | ceph-rgw | [u'openstack'] | + | cinder | [u'openstack'] | + | dcdbsync | [u'openstack'] | + | fm-rest-api | [u'openstack'] | + | garbd | [u'openstack'] | + | glance | [u'openstack'] | + | gnocchi | [u'openstack'] | + | heat | [u'openstack'] | + | horizon | [u'openstack'] | + | ingress | [u'kube-system', u'openstack'] | + | ironic | [u'openstack'] | + | keystone | [u'openstack'] | + | keystone-api-proxy | [u'openstack'] | + | libvirt | [u'openstack'] | + | mariadb | [u'openstack'] | + | memcached | [u'openstack'] | + | networking-avs | [u'openstack'] | + | neutron | [u'openstack'] | + | nginx-ports-control | [] | + | nova | [u'openstack'] | + | nova-api-proxy | [u'openstack'] | + | openstack-helm-toolkit | [] | + | openstack-psp-rolebinding | [u'openstack'] | + | openvswitch | [u'openstack'] | + | panko | [u'openstack'] | + | placement | [u'openstack'] | + | rabbitmq | [u'openstack'] | + +---------------------------+--------------------------------+ + +The attribute values of an OpenStack Service's Helm chart represents the +configurable parameters of the OpenStack Service. The OpenStack Services' helm +charts are defined upstream +here: `https://opendev.org/openstack/openstack-helm `__. +The specific attribute values supported by a helm chart can be found in the +values.yaml file under the particular OpenStack Service, +e.g. `https://opendev.org/openstack/openstack-helm/src/branch/master/nova/values.yaml `__. + +After uploading the |prod| application, |prod| applies 'system' overrides +to the OpenStack helm charts, to specify a default configuration of +containerized |prod| on |prod|. To display those 'system' overrides: + +.. parsed-literal:: + + ~(keystone_admin)]$ system helm-override-show |prefix|-openstack nova openstack + +You can specify helm overrides to update additional helm chart values and/or +modify the overrides made by the system. The command syntax is: + +.. code-block:: none + + system helm-override-update [--reuse-values] [--reset-values] [--values ] [--set ] app-name chart-name namespace + +The optional arguments are: + +``--reuse-values`` + Determines if we should reuse existing helm chart user override values. + If ``--reset-values`` is set, then this argument is ignored. + +``--reset-values`` + Replace any existing helm chart overrides with the ones specified. + +``--values `` + Specify a YAML file containing helm chart override values. Can specify + multiple times. + +``--set `` + Set helm chart override values on the command line. Multiple override + values can be specified with multiple ``--set`` arguments. These are + processed after ``--values`` files. + +The updated overridden helm chart values are applied to the OpenStack +Application the next time |prefix|-openstack is run. + +As some examples of using helm chart overrides to configure OpenStack services +of |prod|, the following sections show a few examples of some +typical configurable changes to |prod|. diff --git a/doc/source/system_configuration/system-configuration-starlingx-application-package-manager.rst b/doc/source/system_configuration/system-configuration-starlingx-application-package-manager.rst new file mode 100644 index 000000000..59afa2dce --- /dev/null +++ b/doc/source/system_configuration/system-configuration-starlingx-application-package-manager.rst @@ -0,0 +1,69 @@ + +.. gsl1568831180133 +.. _system-configuration-starlingx-application-package-manager: + +===================================== +StarlingX Application Package Manager +===================================== + +Use the |prod| system application commands to manage containerized +applications provided as part of |prod|. + +StarlingX application management provides a wrapper around Airship Armada +\(see `https://opendev.org/airship/armada.git `__\) +and Kubernetes Helm \(see `https://github.com/helm/helm `__\) +for managing containerized applications. Armada is a tool for managing +multiple Helm charts with dependencies by centralizing all configurations +in a single Armada YAML definition and providing life-cycle hooks for all +Helm releases. + +A StarlingX application package is a compressed tarball containing a +metadata.yaml file, a manifest.yaml Armada manifest file, and a charts +directory containing helm charts and a checksum.md5 file. The metadata.yaml +file contains the application name, version, and optional helm repository +and disabled charts information. + +StarlingX application package management provides a set of :command:`system` +CLI commands for managing the lifecycle of an Application, which includes +managing overrides to the helm charts within the application. + +.. _system-configuration-starlingx-application-package-manager-d123e61: + +.. table:: Table 1. Application Package Manager Commands + :widths: auto + + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Command | Description | + +========================================+=============================================================================================================================================================================================================================================================+ + | :command:`application-list` | List all applications. | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :command:`application-show` | Show application details such as name, status, and progress. | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :command:`application-upload` | Upload a new application package. | + | | | + | | This command loads the application's armada manifest and helm charts into an internal database and automatically applies system overrides for well-known helm charts, allowing the helm chart to be applied optimally to the current cluster configuration. | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :command:`helm-override-list` | List system helm charts and the namespaces with helm chart overrides for each helm chart. | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :command:`helm-override-show` | Show a helm chart's overrides for a particular namespace. | + | | | + | | This command displays system-overrides, user-overrides and the combined system and user overrides. | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :command:`helm-override-update` | Update helm chart user-overrides for a particular namespace. | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :command:`helm-chart-attribute-modify` | Enable or disable the installation of a particular helm chart within an application manifest. | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :command:`helm-override-delete` | Delete a helm chart's user-overrides for a particular namespace. | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :command:`application-apply` | Apply or reapply the application manifest and helm charts. | + | | | + | | This command will install or update the existing installation of the application based on its armada manifest, helm charts and helm charts' combined system and user overrides. | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :command:`application-abort` | Abort the current application operation. | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :command:`application-update` | Update the deployed application to a different version | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :command:`application-remove` | Uninstall an application. | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :command:`application-delete` | Remove the uninstalled application's definition, including manifest and helm charts and helm chart overrides, from the system. | + +----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/doc/source/system_configuration/using-helm-overrides-to-enable-internal-dns.rst b/doc/source/system_configuration/using-helm-overrides-to-enable-internal-dns.rst new file mode 100644 index 000000000..46421fae1 --- /dev/null +++ b/doc/source/system_configuration/using-helm-overrides-to-enable-internal-dns.rst @@ -0,0 +1,35 @@ + +.. bbr1591372608382 +.. _using-helm-overrides-to-enable-internal-dns: + +============================== +Enable Internal DNS in Neutron +============================== + +You can use Helm overrides to enable internal DNS support. + +.. rubric:: |proc| + +#. Create a yaml file to enable internal dns resolution for neutron. + + .. code-block:: none + + ~(keystone_admin)]$ cat > neutron-overrides.yaml <