diff --git a/doc/source/admin/configuring.rst b/doc/source/admin/configuring.rst index c0aabac1a0..4c4c74744c 100644 --- a/doc/source/admin/configuring.rst +++ b/doc/source/admin/configuring.rst @@ -55,4 +55,4 @@ pipeline, you can create a file under the file path defined by ``disable_by_file_path`` ie. ``/etc/magnum/healthcheck_disable``. For more information see -`oslo.middleware `_. +`oslo.middleware `_. diff --git a/doc/source/admin/troubleshooting-guide.rst b/doc/source/admin/troubleshooting-guide.rst index 5e8c6826a1..ef075670b0 100644 --- a/doc/source/admin/troubleshooting-guide.rst +++ b/doc/source/admin/troubleshooting-guide.rst @@ -1,3 +1,5 @@ +.. _magnum_troubleshooting_guide: + ============================ Magnum Troubleshooting Guide ============================ @@ -239,16 +241,17 @@ Check the following: interface? Does this interface have a route to the external internet? - If "external-network" is specified in the ClusterTemplate, does this network have a route to the external internet? -- Is your devstack environment behind a firewall? This can be the case for some - enterprises or countries. In this case, consider using a `proxy server - `_. +- Is your devstack environment behind a firewall? This can be the + case for some + enterprises or countries. In this case, consider using a + :doc:`proxy server `. - Is the traffic blocked by the security group? Check the `rules of security group - `_. + `_. - Is your host NAT'ing your internal network correctly? Check your host - `iptables `_. + `iptables `_. - Use *tcpdump* for `networking troubleshooting - `_. + `_. You can run *tcpdump* on the interface *docker0, flannel0* and *eth0* on the node and then run *ping* to see the path of the message from the container. @@ -266,7 +269,7 @@ If the name lookup fails, check the following: specified by "dns-nameserver" in the ClusterTemplate. - If you are using your own DNS server by specifying "dns-nameserver" in the ClusterTemplate, is it reachable and working? -- More help on `DNS troubleshooting `_. +- More help on `DNS troubleshooting `_. Kubernetes networking @@ -354,7 +357,7 @@ If the ping is not successful, check the following: - Is Flannel running properly? check the `Running Flannel`_. - Ping and try `tcpdump - `_ + `_ on each network interface along the path between two nodes to see how far the message is able to travel. The message path should be as follows: diff --git a/doc/source/contributor/functional-test.rst b/doc/source/contributor/functional-test.rst index a034d29a1f..c6e481eecd 100644 --- a/doc/source/contributor/functional-test.rst +++ b/doc/source/contributor/functional-test.rst @@ -9,10 +9,9 @@ Prerequisite ============ You need to have a Magnum instance running somewhere. If you are using -devstack, follow the developer quickstart guide to deploy Magnum in a devstack -environment +devstack, follow :ref:`quickstart` to deploy Magnum in a devstack +environment. -``_ Configuration ============= @@ -66,7 +65,7 @@ Outside of devstack If you are not using devstack, you'll need to create the configuration files. The /etc/tempest.conf configuration file is documented here -``_ +``_ Here's a reasonable sample of tempest.conf settings you might need:: diff --git a/doc/source/contributor/objects.rst b/doc/source/contributor/objects.rst index a3726b6008..b7bbdbcdc4 100644 --- a/doc/source/contributor/objects.rst +++ b/doc/source/contributor/objects.rst @@ -18,7 +18,7 @@ Versioned Objects ================= Magnum uses the `oslo.versionedobjects library -`_ to +`_ to construct an object model that can be communicated via RPC. These objects have a version history and functionality to convert from one version to a previous version. This allows for 2 different levels of the code to still pass objects @@ -30,7 +30,7 @@ Object Version Testing In order to ensure object versioning consistency is maintained, oslo.versionedobjects has a fixture to aid in testing object versioning. `oslo.versionedobjects.fixture.ObjectVersionChecker -`_ +`_ generates fingerprints of each object, which is a combination of the current version number of the object, along with a hash of the RPC-critical parts of the object (fields and remotable methods). @@ -61,7 +61,7 @@ This results in a unit test failure with the following output: .. code-block:: console - : Fields or remotable methods in some objects have changed. Make sure the versions of the objects has been bumped, and update the hashes in the static fingerprints tree (object_data). For more information, read http://docs.openstack.org/developer/magnum/objects.html. + : Fields or remotable methods in some objects have changed. Make sure the versions of the objects has been bumped, and update the hashes in the static fingerprints tree (object_data). For more information, read https://docs.openstack.org/developer/magnum/objects.html. This is an indication that me adding the 'foo' field to Cluster means I need to bump the version of Cluster, so I increase the version and add a comment diff --git a/doc/source/contributor/policies.rst b/doc/source/contributor/policies.rst index ace07fca29..276cb4485f 100644 --- a/doc/source/contributor/policies.rst +++ b/doc/source/contributor/policies.rst @@ -133,7 +133,7 @@ Summary of Core Reviewer Responsibilities PTL Responsibilities ==================== In accordance with our `Project Team Guide for PTLs -`_ +`_ our PTL carries all the responsibilities referenced above plus: * Select and target blueprints for each release cycle. @@ -310,9 +310,9 @@ Reviews ======= A review is a patch set that includes a proposal for inclusion in our code base. We follow the process outlined in the `Code Review -`_ +`_ section of the `OpenStack Developer's Guide -`_. +`_. The following workflow states may by applied to each review: ========== ================== ============================================= @@ -478,7 +478,7 @@ applied. Fast Revert ----------- This policy was adapted from nova's `Reverts for Retrospective Vetos -`_ policy in 2017. +`_ policy in 2017. Sometimes our simple `2 +2s` approval policy will result in errors when we move quickly. These errors might be a bug that was missed, or equally importantly, it might be that other cores feel that there is a need for diff --git a/doc/source/contributor/quickstart.rst b/doc/source/contributor/quickstart.rst index 76b9c8a817..7f850740cc 100644 --- a/doc/source/contributor/quickstart.rst +++ b/doc/source/contributor/quickstart.rst @@ -10,7 +10,7 @@ OpenStack project. .. seealso:: - http://docs.openstack.org/infra/manual/developers.html + https://docs.openstack.org/infra/manual/developers.html Setup Dev Environment ===================== @@ -57,7 +57,7 @@ Magnum source code should be pulled directly from git:: # from your home or source directory cd ~ - git clone https://git.openstack.org/openstack/magnum + git clone https://opendev.org/openstack/magnum cd magnum All unit tests should be run using tox. To run magnum's entire test suite:: @@ -84,7 +84,7 @@ To run unit test coverage and check percentage of code covered:: tox -e cover To discover and interact with templates, please refer to -``_ +:doc:`/user/cluster-type-definition`. Exercising the Services Using DevStack ====================================== @@ -113,7 +113,7 @@ Clone devstack:: sudo mkdir -p /opt/stack sudo chown $USER /opt/stack - git clone https://git.openstack.org/openstack-dev/devstack /opt/stack/devstack + git clone https://opendev.org/openstack/devstack /opt/stack/devstack We will run devstack with minimal local.conf settings required to enable magnum, heat, and neutron (neutron is enabled by default in devstack since @@ -130,16 +130,16 @@ Kilo, and heat must be enabled by yourself):: PUBLIC_INTERFACE=eth1 # Enable barbican service and use it to store TLS certificates - # For details https://docs.openstack.org/developer/magnum/userguide.html#transport-layer-security - enable_plugin barbican https://git.openstack.org/openstack/barbican + # For details https://docs.openstack.org/magnum/latest/user/index.html#transport-layer-security + enable_plugin barbican https://opendev.org/openstack/barbican - enable_plugin heat https://git.openstack.org/openstack/heat + enable_plugin heat https://opendev.org/openstack/heat # Enable magnum plugin after dependent plugins - enable_plugin magnum https://git.openstack.org/openstack/magnum + enable_plugin magnum https://opendev.org/openstack/magnum # Optional: uncomment to enable the Magnum UI plugin in Horizon - #enable_plugin magnum-ui https://github.com/openstack/magnum-ui + #enable_plugin magnum-ui https://opendev.org/openstack/magnum-ui VOLUME_BACKING_FILE_SIZE=20G END @@ -152,8 +152,8 @@ Optionally, you can enable neutron/lbaas v2 with octavia to create load balancers for multi master clusters:: $ cat >> /opt/stack/devstack/local.conf << END - enable_plugin neutron-lbaas https://git.openstack.org/openstack/neutron-lbaas - enable_plugin octavia https://git.openstack.org/openstack/octavia + enable_plugin neutron-lbaas https://opendev.org/openstack/neutron-lbaas + enable_plugin octavia https://opendev.org/openstack/octavia # Disable LBaaS(v1) service disable_service q-lbaas @@ -170,7 +170,7 @@ Optionally, you can enable ceilometer in devstack. If ceilometer is enabled, magnum will periodically send metrics to ceilometer:: $ cat >> /opt/stack/devstack/local.conf << END - enable_plugin ceilometer https://git.openstack.org/openstack/ceilometer + enable_plugin ceilometer https://opendev.org/openstack/ceilometer END If you want to deploy Docker Registry 2.0 in your cluster, you should enable @@ -184,10 +184,10 @@ swift in devstack:: END More devstack configuration information can be found at -http://docs.openstack.org/developer/devstack/configuration.html +https://docs.openstack.org/devstack/latest/configuration.html More neutron configuration information can be found at -http://docs.openstack.org/developer/devstack/guides/neutron.html +https://docs.openstack.org/devstack/latest/guides/neutron.html Run devstack:: @@ -391,8 +391,7 @@ cluster using:: sudo mv ./kubectl /usr/local/bin/kubectl We first need to setup the certs to allow Kubernetes to authenticate our -connection. Please refer to -``_ +connection. Please refer to :ref:`transport_layer_security` for more info on using TLS keys/certs which are setup below. To generate an RSA key, you will use the 'genrsa' command of the 'openssl' @@ -550,7 +549,7 @@ except for the absence of some Kubernetes-specific arguments and the use of --coe swarm-mode **NOTE:** If you are using Magnum behind a firewall then refer -to ``_ +to :doc:`/admin/magnum-proxy`. Finally, create the cluster. Use the ClusterTemplate 'swarm-cluster-template' as a template for cluster creation. This cluster will result in one swarm @@ -658,7 +657,7 @@ Building and Using a Mesos Cluster Provisioning a mesos cluster requires a Ubuntu-based image with some packages pre-installed. To build and upload such image, please refer to -``_ +:ref`building_mesos_image`. Alternatively, you can download and upload a pre-built image:: diff --git a/doc/source/contributor/reno.rst b/doc/source/contributor/reno.rst index 98bb4eb4a7..0db7219532 100644 --- a/doc/source/contributor/reno.rst +++ b/doc/source/contributor/reno.rst @@ -4,7 +4,7 @@ Release Notes What is reno ? -------------- -Magnum uses `reno `_ for +Magnum uses `reno `_ for providing release notes in-tree. That means that a patch can include a *reno file* or a series can have a follow-on change containing that file explaining what the impact is. @@ -19,7 +19,7 @@ generated using the reno tool this way: where usually ```` can be ``bp-`` for a blueprint or ``bug-XXXXXX`` for a bugfix. -Refer to the `reno documentation `_ +Refer to the `reno documentation `_ for the full list of sections. @@ -32,10 +32,10 @@ of the note file entirely. If no section is needed, then you know you don't need to provide a release note :-) * ``upgrade`` - * The patch has an `UpgradeImpact `_ tag + * The patch has an `UpgradeImpact `_ tag * A DB change needs some deployer modification (like a migration) * A configuration option change (deprecation, removal or modified default) - * some specific changes that have a `DocImpact `_ tag + * some specific changes that have a `DocImpact `_ tag but require further action from an deployer perspective * any patch that requires an action from the deployer in general @@ -43,7 +43,7 @@ need to provide a release note :-) * If the patch fixes a known vulnerability * ``features`` - * If the patch has an `APIImpact `_ tag + * If the patch has an `APIImpact `_ tag * ``critical`` * Bugfixes categorized as Critical in Launchpad *impacting users* diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index e64f188317..55aaf9a647 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -21,5 +21,5 @@ runs that image in either virtual machines or bare metal in a cluster configuration. This chapter assumes a working setup of OpenStack following `OpenStack -Installation Tutorial `_. +Installation Tutorial `_. diff --git a/doc/source/install/install-guide-from-source.rst b/doc/source/install/install-guide-from-source.rst index ff7fe7b6b3..3ee2a2c013 100644 --- a/doc/source/install/install-guide-from-source.rst +++ b/doc/source/install/install-guide-from-source.rst @@ -105,7 +105,7 @@ Install and configure components .. code-block:: console # cd /var/lib/magnum - # git clone https://git.openstack.org/openstack/magnum.git + # git clone https://opendev.org/openstack/magnum # chown -R magnum:magnum magnum # cd magnum # su -s /bin/sh -c "/var/lib/magnum/env/bin/pip install -r requirements.txt" magnum @@ -254,7 +254,7 @@ Install the command-line client .. code-block:: console $ cd ~ - $ git clone https://git.openstack.org/openstack/python-magnumclient.git + $ git clone https://opendev.org/openstack/python-magnumclient $ cd python-magnumclient $ virtualenv .magnumclient-env $ .magnumclient-env/bin/pip install -r requirements.txt diff --git a/doc/source/install/install.rst b/doc/source/install/install.rst index bbf2867bc3..fac2370ab9 100644 --- a/doc/source/install/install.rst +++ b/doc/source/install/install.rst @@ -9,28 +9,30 @@ Infrastructure Management service, code-named magnum, on the controller node. This section assumes that you already have a working OpenStack environment with at least the following components installed: Identity service, Image service, Compute service, Networking service, Block Storage service and Orchestration -service. See `OpenStack Install Guides `__. To provide access to Docker Swarm or Kubernetes using the native clients (docker or kubectl, respectively) magnum uses TLS certificates. To store the certificates, it is recommended to use the `Key Manager service, code-named -barbican `__, or you can save them in magnum's database. Optionally, you can install the following components: -- `Load Balancer as a Service (LBaaS v2) `__ to create clusters with multiple +- `Load Balancer as a Service (LBaaS v2) `__ to create clusters with multiple masters -- `Bare Metal service `__ to create baremetal clusters -- `Object Storage service `__ to make private Docker registries available to +- `Bare Metal service + `__ + to create baremetal clusters +- `Object Storage service + `__ + to make private Docker registries available to users -- `Telemetry Data Collection service `__ to periodically send - magnum-related metrics +- `Telemetry Data Collection service + `__ + to periodically send magnum-related metrics .. note:: diff --git a/doc/source/install/launch-instance.rst b/doc/source/install/launch-instance.rst index 675313b51e..279bbda79f 100644 --- a/doc/source/install/launch-instance.rst +++ b/doc/source/install/launch-instance.rst @@ -6,9 +6,9 @@ Launch an instance In environments that include the Container Infrastructure Management service, you can provision container clusters made up of virtual machines or baremetal servers. The Container Infrastructure Management service uses -`Cluster Templates `__ -to describe how a `Cluster `__ is constructed. In each of the following examples +`Cluster Templates `_ +to describe how a :ref:`cluster` is constructed. In each of the +following examples you will create a Cluster Template for a specific COE and then you will provision a Cluster using the corresponding Cluster Template. Then, you can use the appropriate COE client or endpoint to create containers. diff --git a/doc/source/install/next-steps.rst b/doc/source/install/next-steps.rst index 6583c0f9a8..3cd3633f27 100644 --- a/doc/source/install/next-steps.rst +++ b/doc/source/install/next-steps.rst @@ -6,4 +6,4 @@ Next steps Your OpenStack environment now includes the magnum service. To add more services, see the `additional documentation on installing OpenStack -`_ . +`_ . diff --git a/doc/source/user/cluster-type-definition.rst b/doc/source/user/cluster-type-definition.rst index cfdc1d8210..f25e2e826f 100644 --- a/doc/source/user/cluster-type-definition.rst +++ b/doc/source/user/cluster-type-definition.rst @@ -45,7 +45,7 @@ Enabling a Cluster Type is as simple as adding it's Entry Point to the $ virtualenv .venv $ . .venv/bin/active - (.venv)$ git clone https://github.com/openstack/magnum.git + (.venv)$ git clone https://opendev.org/openstack/magnum (.venv)$ cd magnum (.venv)$ python setup.py install diff --git a/doc/source/user/glossary.rst b/doc/source/user/glossary.rst index 22bdabd205..f27aaa7086 100644 --- a/doc/source/user/glossary.rst +++ b/doc/source/user/glossary.rst @@ -1,3 +1,5 @@ +.. _glossary: + ======== Glossary ======== diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index ad40060fc8..6021615919 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -420,6 +420,8 @@ the table are linked to more details elsewhere in the user guide. | | - false | | +---------------------------------------+--------------------+---------------+ +.. _cluster: + Cluster ------- @@ -503,9 +505,7 @@ network cannot be removed while a Nova instance is still attached. **NOTE** Currently Heat nested templates are used to create the resources; therefore if an error occurs, you can troubleshoot through Heat. For more help on Heat stack troubleshooting, refer to the -`Troubleshooting Guide -`_. - +:ref:`magnum_troubleshooting_guide`. Create @@ -700,11 +700,11 @@ Follow the instructions in the OpenStack Installation Guide to enable the repositories for your distribution: * `RHEL/CentOS/Fedora - `_ + `_ * `Ubuntu/Debian - `_ + `_ * `openSUSE/SUSE Linux Enterprise - `_ + `_ Install using distribution packages for RHEL/CentOS/Fedora:: @@ -730,7 +730,7 @@ Using the command-line client ----------------------------- Refer to the `OpenStack Command-Line Interface Reference -`_ for a full list of the +`_ for a full list of the commands supported by the `openstack coe` command-line client. Horizon Interface @@ -739,11 +739,10 @@ Horizon Interface Magnum provides a Horizon plugin so that users can access the Container Infrastructure Management service through the OpenStack browser-based graphical UI. The plugin is available from -`magnum-ui `_. It is not +`magnum-ui `_. It is not installed by default in the standard Horizon service, but you can follow the instruction for `installing a Horizon plugin -`_. +`_. In Horizon, the container infrastructure panel is part of the 'Project' view and it currently supports the following operations: @@ -1015,8 +1014,7 @@ look for the attribute *coe_version* and *container_version*:: Kubernetes ========== Kubernetes uses a range of terminology that we refer to in this guide. We -define these common terms in the `Glossary -`_ for your reference. +define these common terms in the :ref:`Glossary` for your reference. When Magnum deploys a Kubernetes cluster, it uses parameters defined in the ClusterTemplate and specified on the cluster-create command, for example:: @@ -1757,6 +1755,8 @@ _`mesos_slave_executor_env_variables` variables. +.. _building_mesos_image: + Building Mesos image -------------------- @@ -1774,7 +1774,7 @@ Diskimage-builder +++++++++++++++++ To run the `diskimage-builder -`__ tool +`__ tool manually, use the provided `elements `__. Following are the typical steps to use the diskimage-builder tool on @@ -1784,10 +1784,10 @@ an Ubuntu server:: $ sudo apt-get install git qemu-utils python-pip $ sudo pip install diskimage-builder - $ git clone https://git.openstack.org/openstack/magnum - $ git clone https://git.openstack.org/openstack/dib-utils.git - $ git clone https://git.openstack.org/openstack/tripleo-image-elements.git - $ git clone https://git.openstack.org/openstack/heat-templates.git + $ git clone https://opendev.org/openstack/magnum + $ git clone https://opendev.org/openstack/dib-utils.git + $ git clone https://opendev.org/openstack/tripleo-image-elements.git + $ git clone https://opendev.org/openstack/heat-templates.git $ export PATH="${PWD}/dib-utils/bin:$PATH" $ export ELEMENTS_PATH=tripleo-image-elements/elements:heat-templates/hot/software-config/elements:magnum/magnum/drivers/mesos_ubuntu_v1/image/mesos $ export DIB_RELEASE=trusty @@ -1806,7 +1806,7 @@ provided `Dockerfile The output image will be saved as '/tmp/ubuntu-mesos.qcow2'. Following are the typical steps to run a Docker container to build the image:: - $ git clone https://git.openstack.org/openstack/magnum + $ git clone https://opendev.org/openstack/magnum $ cd magnum/magnum/drivers/mesos_ubuntu_v1/image $ sudo docker build -t magnum/mesos-builder . $ sudo docker run -v /tmp:/output --rm -ti --privileged magnum/mesos-builder @@ -1849,6 +1849,7 @@ For example, you can 'post' a JSON app description to $ curl -X POST -H "Content-Type: application/json" \ http://${API_ADDRESS}:8080/v2/apps -d@app.json +.. _transport_layer_security: Transport Layer Security ======================== @@ -2918,7 +2919,7 @@ This image can be downloaded from the `public Atomic site `_ or can be built locally using diskimagebuilder. Details can be found in the `fedora-atomic element -`_ +`_ The image currently has the following OS/software: +--------------------------+-----------+ @@ -2996,7 +2997,7 @@ Kubernetes on Ironic This image is built manually using diskimagebuilder. The scripts and instructions are included in `Magnum code repo -`_. +`_. Currently Ironic is not fully supported yet, therefore more details will be provided when this driver has been fully tested. @@ -3048,7 +3049,7 @@ capabilities for compliance with security, operational, and business processes and supports normalized and categorized event data for federation and aggregation. -.. _PyCADF: http://docs.openstack.org/developer/pycadf +.. _PyCADF: https://docs.openstack.org/pycadf .. _CADF: http://www.dmtf.org/standards/cadf Below table describes the event model components and semantics for diff --git a/doc/source/user/kubernetes-load-balancer.rst b/doc/source/user/kubernetes-load-balancer.rst index ed6510b972..7dbf30f5a6 100644 --- a/doc/source/user/kubernetes-load-balancer.rst +++ b/doc/source/user/kubernetes-load-balancer.rst @@ -128,8 +128,8 @@ Create a file (e.g nginx-service.yaml) describing a service for the nginx pod:: app: nginx type: LoadBalancer -Please refer to the `quickstart `_ guide on how to connect to Kubernetes running on the launched +Please refer to :ref:`quickstart` on how to connect to Kubernetes +running on the launched cluster. Assuming a Kubernetes cluster named k8sclusterv1 has been created, deploy the pod and service using following commands::