diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 76502236..5a56be99 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -1,8 +1,10 @@ # Leave a blank line at the end of this file to support concatenation apache AthenaV2 +az backend backends +balancers Caracal ceph Charmcraft @@ -12,9 +14,11 @@ config configs cryptographically DHSS +distributable dvipng fonts freefont +functest github GPG gyre @@ -25,6 +29,7 @@ IDP IDPs Intersphinx io +ipv JDK Jira Kanban @@ -33,16 +38,20 @@ Keycloak lang LaTeX latexmk +lnav manila Manila +microceph Multipass neutronclient +octavia oidc openidc OpenIDC openstack openstackclient openstackclients +OSCI otf plantuml PNG @@ -52,10 +61,14 @@ Pygments QEMU readthedocs Rockcraft +routable rst rsync +samltestid +sg sitemapindex sos +ssl SSL stsstack STSStack @@ -73,6 +86,8 @@ uncommenting URIs url utils +vips +vm VMs WCAG webhook diff --git a/docs/conf.py b/docs/conf.py index cc61c40c..0f0078c3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -251,6 +251,7 @@ # myst_enable_extensions = set() +# myst_heading_anchors = 3 # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html diff --git a/docs/index.rst b/docs/index.rst index 284f612e..d741e1bd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,17 +3,17 @@ STSStack-Bundles Documentation STSStack-Bundles is a set of bundles that leverage Juju bundle overlays to allow generating complex deployments from a number of options using a single command. These bundles are designed for use with the Juju OpenStack provider. -The top level directory contains a set of modules, each of which has a generate-bundle.sh script which you can use to create a deployment from a number of options. +The top level directory contains a set of modules, each of which has a ``generate-bundle.sh`` script which you can use to create a deployment from a number of options. -NOTE: see generate-bundle.sh --help for option info about using that particular module. +NOTE: see :doc:`user-docs/generate-bundle` ``--help`` for option info about using that particular module. Basic usage: - * give your deployment a name with (--name) + * give your deployment a name with (``--name``) * create a Juju model using the given name or use existing one - * add one or more feature overlays depending on what you need (see --list-overlays) - * resources are stored under a named directory so as to be able to avoid collisions and replay later (--replay) - * immediate deploy (--run) or save for later + * add one or more feature overlays depending on what you need (see ``--list-overlays``) + * resources are stored under a named directory so as to be able to avoid collisions and replay later (``--replay``) + * immediate deploy (``--run``) or save for later .. toctree:: @@ -39,4 +39,3 @@ In this documentation :link-type: doc **For contributors** - how to contribute to STSStack-Bundles. - diff --git a/docs/user-docs/generate-bundle.rst b/docs/user-docs/generate-bundle.rst new file mode 100644 index 00000000..7c11773a --- /dev/null +++ b/docs/user-docs/generate-bundle.rst @@ -0,0 +1,29 @@ +generate-bundle.sh +================== + +The `generate-bundle.sh` script is used to create a bundle, and optionally deploy it, of a Charmed OpenStack, Kubernetes, or Ceph deployment. + +Usage +----- + +Run the script from the project root: + +.. code:: + + ./generate-bundle.sh + +This will generate the necessary files for deployment in the `b` directory. + +Options +------- + +You can pass additional options to customise the build process. For example: + +.. code:: + + ./generate-bundle.sh --keystone-ha --num-compute 2 --run + +Prerequisites +------------- + +Make sure you have all required dependencies installed before running the script. diff --git a/docs/user-docs/index.rst b/docs/user-docs/index.rst index 769bb088..5609cc35 100644 --- a/docs/user-docs/index.rst +++ b/docs/user-docs/index.rst @@ -6,6 +6,7 @@ User Documentation :maxdepth: 2 usage + generate-bundle.sh openstack/index ceph/index osm/index diff --git a/docs/user-docs/openstack/index.md b/docs/user-docs/openstack/index.md index 80d80132..fc280c9d 100644 --- a/docs/user-docs/openstack/index.md +++ b/docs/user-docs/openstack/index.md @@ -15,6 +15,7 @@ OVN SAML Keystone + OpenIDC Manila +Tools ``` ````{grid} 1 1 2 2 @@ -89,4 +90,9 @@ Dynamic Routing :link-type: doc **Tutorial** - learn how to deploy an OpenStack cloud on `serverstack` ``` +```{grid-item-card} Tools +:link: tools +:link-type: doc +**Tools** - OpenStack Tools +``` ```` diff --git a/docs/user-docs/openstack/tools.md b/docs/user-docs/openstack/tools.md new file mode 100644 index 00000000..fd2a58ed --- /dev/null +++ b/docs/user-docs/openstack/tools.md @@ -0,0 +1,232 @@ +# Tools + +After a successful OpenStack deployment via `./generate-bundle.sh` (see [Usage](../usage.rst)), there are a few scripts in `openstack/tools` that might be helpful. + +## `allocate_vips.sh` + +Allocate the last 20 IP addresses of the network `subnet_${OS_USERNAME}-psd`, which could be considered for VIPs in OpenStack + +### Example + +```console +allocate_vips.sh +``` + +## `charmed_openstack_functest_runner.sh` + +Run OpenStack charms functional tests manually in a similar way to how Openstack CI (OSCI) would do it. This tool should be run from within a charm root. + +Not all charms use the same versions and dependencies and an attempt is made to cover this here but in some cases needs to be dealt with as a pre-requisite to running the tool. For example some charms need their tests to be run using python 3.8 and others python 3.10. Some tests might require Juju 2.9 and others Juju 3.x - the assumption in this runner is that Juju 3.x is good to use. + +### Example + +```console +charmed_openstack_functest_runner.sh +``` + +(configure-octavia-sh)= +## `configure_octavia.sh` + +Configures a new Octavia deployment. Assumes that the amphora image has been added to Glance already (see ...). + +### Example + +```console +configure_octavia.sh +``` + +## `create_ipv4_octavia.sh` + +Configure Octavia deployment to use an `IPv4` `lp-mgmt-net`. + +### Example + +```console +create_ipv4_octavia.sh +``` + +## `create_nova_az_aggregates.sh` + +Create Nova Aggregates for two sets of `nova-compute` units. The script assumes that the compute hosts are divided into two zones, and that the `nova-compute` application was named according to: + +```console +juju deploy nova-compute nova-compute-az1 +juju deploy nova-compute nova-compute-az2 +``` + +The script takes all units in each set and creates Nova Aggregates for these. + +### Example + +```console +create_nova_az_aggregates.sh +``` + +## `create_octavia_lb.sh` + +Create a load balancer with Octavia. This command assumes that Octavia has been properly configured, see [`configure_octavia.sh`](#configure-octavia-sh) and `upload_octavia_amphora_image.sh` for details. + +### Example + +```console +create_octavia_lb.sh --name lb \ + --member-vm server-1 \ + --provider amphora \ + --protocol TCP \ + --protocol-port 22 +``` + +## `create_project.sh` + +Create a new project. The command takes up to three optional arguments: + +### Usage + +```console +create_project.sh [PROJECT_NAME [USER_DOMAIN [NETWORK_CIDR]]] +``` + +The script will create the project, create a user in that project, assign `Member`, `load-balancer_observer`, and `load-balancer_member` roles to that user, and create a new routable network. + +### Example + +```console +create_project.sh new-project +``` + +## `create_sg_log.sh` + +Create logs for security group related events. + +### Example + +```console +create_sg_log.sh +``` + +## `create-microceph-vm.sh` + +Deploys a MicroCeph VM. See + + + +and + + + +### Example + +Deploy using: + +```console +juju add-model microceph +juju deploy --constraints mem=16G --series jammy ubuntu microceph-vm +juju scp openstack/tools/create-microceph-vm.sh microceph-vm/0: +juju ssh microceph-vm/0 -- ./create-microceph-vm.sh +``` + +After everything is deployed, ceph can be used via the ceph command, *e.g.* + +```console +juju ssh microceph-vm/0 -- lxc exec microceph-1 ceph status +``` + +## `delete_project.sh` + +Deletes a project and cleans up any used resources, *e.g.*, servers, networks, load balancers, *etc.*. + +### Example + +```console +delete_project.sh +``` + +## `enable_samltestid.sh` + +Configures Keystone for federation using the `keystone-saml-mellon` charm. + +### Example + +```console +enable_samltestid.sh +``` + +## `float_all.sh` + +Give all servers a floating IP. + +### Example + +```console +float_all.sh +``` + +## `install_local_ca.sh` + +Installs the CA for ssl locally. See [`generate-bundle.sh`](../generate-bundle) + +## `instance_launch.sh` + +Launch a server. + +## `juju-lnav` + +Run [`lnav`](https://lnav.org/), a log viewer on multiple units for tracking log traces across services. + +### Example + +```console +juju-lnav keystone:/var/log/keystone \ + neutron-api:/var/log/neutron \ + nova-cloud-controller:/var/log/nova +``` + +## `openstack_regression_tests_runner.sh` + +Run the OSCI test runner locally. + +## `sec_groups.sh` + +Add standard rules to the default security group, *e.g.* `TCP/22`, `TCP/80`, *etc.* + +### Example + +```console +sec_groups.sh +``` + +## `setup_tempest.sh` + +### Example + +```console +setup_tempest.sh +``` + +## `upload_image.sh` + +### Example + +```console +upload_image.sh +``` + +## `upload_octavia_amphora_image.sh` + +Upload the Octavia Amphora image to Glance. + +### Example + +```console +upload_octavia_amphora_image.sh +``` + +## `vault-unseal-and-authorise.sh` + +Configure `vault`. Has to be run for new deployments or after restarting the `vault` service. + +### Example + +```console +vault-unseal-and-authorise.sh +``` diff --git a/docs/user-docs/usage.rst b/docs/user-docs/usage.rst index 1ddcb5e5..4975ac25 100644 --- a/docs/user-docs/usage.rst +++ b/docs/user-docs/usage.rst @@ -1,7 +1,7 @@ Usage ===== -Using ``stsstack-bundles`` involves generating a bundle and overlays, deploying them then performing some post-deployment actions. +Using `stsstack-bundles` involves generating a bundle and overlays, deploying them then performing some post-deployment actions. As an example, let's say you want to deploy OpenStack using the Caracal release on Jammy and you want to enable Ceph and heat with Keystone in HA: