Skip to content

Add prerequisites doc #376

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
WizardBit wants to merge 1 commit into
base: main
Choose a base branch
from
+60 −28
Open

Add prerequisites doc #376

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 11 additions & 5 deletions docs/user-docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,42 +5,48 @@ User Documentation
:hidden:
:maxdepth: 2

usage
prerequisites
openstack/index
kubernetes/index
ceph/index
osm/index

.. grid:: 1 1 2 2

.. grid-item-card:: Prerequisites
:link: prerequisites
:link-type: doc

**Prerequisites** - setups and info required for stsstack

.. grid-item-card:: Usage
:link: usage
:link-type: doc

**For users and operators** - how to use STSStack-Bundles

.. grid:: 1 1 2 2

.. grid-item-card:: OpenStack
:link: openstack/index
:link-type: doc

**OpenStack** - how to deploy OpenStack

.. grid:: 1 1 2 2

.. grid-item-card:: Kubernetes
:link: kubernetes/index
:link-type: doc

**Kubernetes** - how to deploy Kubernetes

.. grid:: 1 1 2 2

.. grid-item-card:: Ceph
:link: ceph/index
:link-type: doc

**Ceph** - how to deploy Ceph

.. grid:: 1 1 1 1

.. grid-item-card:: OSM
:link: osm/index
:link-type: doc
Expand Down
34 changes: 11 additions & 23 deletions docs/user-docs/openstack/tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,32 +9,16 @@ First some terminology:

The overcloud is deployed onto the undercloud.

## Juju controller
## Prerequisites

Now, first step is to get a juju controller on `Serverstack` (the undercloud).

1. source your `serverstack` `novarc`
2. `juju add-cloud` and follow the prompts; they should be auto-filled with info from the environment after sourcing the `Serverstack` `novarc`
3. `juju autoload-credentials --client`
4. `juju bootstrap serverstack serverstack --bootstrap-constraints="allocate-public-ip=true"`

We want a public (floating) IP here so we can use the controller instance as a jump host for accessing other instances (_e.g._ the units for charmed OpenStack). We can't deploy all units with a public IP because we will reach the quota for floating IPs on `Serverstack`.

## Tunnel into the undercloud network

You will need access to the internal subnet available to you on `Serverstack` (all instances created via juju will have an address on this subnet) - this is so you can do things like juju ssh to the instances, unseal the vault using the `stsstack-bundles` scripts, access the cloud using the openstack CLI, etc. If you are running these steps from inside a bastion instance on `Serverstack`, you may skip this step.

Otherwise, set up a tunnel into your `Serverstack` private subnet. This can be done via `sshuttle` to the juju controller instance (which was deployed with a public floating IP), or any other instance with a public floating IP (_e.g._if you already have a bastion instance). `10.5.0.0/16` is used as an example; your subnet may be different.

```console
sshuttle -r IP_OF_JUJU_CONTROLLER 10.5.0.0/16
```
Be sure to read the [prerequisites](/user-docs/prerequisites) before proceeding to ensure a working environment.

## Deploy the OpenStack overcloud

Now we can start deploying!

Use the `generate-bundle.sh` script in this directory, using the flags to set the desired configuration, and include the `--run` option to deploy it. For example, to create a juju model named `openstack`, and deploy a OpenStack Yoga release on Jammy machines:
Use the `generate-bundle.sh` script in this directory, using the flags to set the desired configuration, and include the `--run` option to deploy it.
For example, to create a juju model named `openstack`, and deploy a OpenStack Yoga release on Jammy machines:

```console
./generate-bundle.sh --name openstack -r yoga -s jammy --run
Expand All @@ -54,7 +38,8 @@ Post-Deployment Info/Actions:
- add rules to default security group: ./tools/sec_groups.sh
```

We'll come back to the post deploy steps, but for now, check `juju status` and wait for all the units to become idle. (Some will remain blocked or waiting; these will be fixed in the post deploy steps.)
We'll come back to the post deploy steps, but for now, check `juju status` and wait for all the units to become idle. (Some will remain blocked or
waiting; these will be fixed in the post deploy steps.)

### Post Deployment

Expand All @@ -66,7 +51,8 @@ First, unseal the vault:
./tools/vault-unseal-and-authorise.sh
```

Then the configure script, passing `serverstack` argument as the profile. For deployments on other OpenStack underclouds, see available profiles in `./profiles/`.
Then the configure script, passing `serverstack` argument as the profile. For deployments on other OpenStack underclouds, see available profiles in
`./profiles/`.

Before running this, ensure your `novarc` file for your `Serverstack` user is available at `~/novarc`.
If this is not possible, search the scripts for `~/novarc` and update the path to point to your `Serverstack` `novarc` file.
Expand All @@ -75,7 +61,9 @@ If this is not possible, search the scripts for `~/novarc` and update the path t
./configure serverstack
```

A final optional step is to set up some default rules for the overcloud security groups. This also demonstrates use of the overcloud `./novarc` file that extracts the required authentication information for the overcloud, setting the appropriate `OS_*` variables in the environment. This script only supports bash, and requires the openstack model to be active in juju.
A final optional step is to set up some default rules for the overcloud security groups. This also demonstrates use of the overcloud `./novarc` file
that extracts the required authentication information for the overcloud, setting the appropriate `OS_*` variables in the environment.
This script only supports bash, and requires the openstack model to be active in juju.

```console
source ./novarc
Expand Down
38 changes: 38 additions & 0 deletions docs/user-docs/prerequisites.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
Prerequisites
=============

These are the general prerequisites required to follow along with the tutorials.

Juju controller
---------------

Get a juju controller on ``Serverstack`` (the undercloud).
Copy link
Copy Markdown
Contributor

@nicolasbock nicolasbock Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is serverstack still up? I like the refactoring of the instructions, but we should follow up with updating where to deploy. Most of us are probably using PS7 now.

Copy link
Copy Markdown
Contributor Author

@WizardBit WizardBit Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought serverstack was just referencing any server as this repo is public.


1. source your ``serverstack`` ``novarc``
2. ``juju add-cloud`` and follow the prompts; they should be auto-filled with info from the environment after sourcing the ``Serverstack`` ``novarc``
3. ``juju autoload-credentials --client``
4. ``juju bootstrap serverstack serverstack --bootstrap-constraints="allocate-public-ip=true"``

We want a public (floating) IP here so we can use the controller instance as a jump host for accessing other instances (e.g. the units for charmed OpenStack).
We can't deploy all units with a public IP because we will reach the quota for floating IPs on ``Serverstack``.

Tunnel into the undercloud network
----------------------------------

You will need access to the internal subnet available to you on ``Serverstack`` (all instances created via juju will have an address on this subnet).
This is so you can do things like juju ssh to the instances, unseal the vault using the ``stsstack-bundles`` scripts, access the cloud using the openstack CLI, etc.
If you are running these steps from inside a bastion instance on ``Serverstack``, you may skip this step.

Otherwise, set up a tunnel into your ``Serverstack`` private subnet. This can be done via ``sshuttle`` to the juju controller instance
(which was deployed with a public floating IP), or any other instance with a public floating IP (e.g. if you already have a bastion instance).
``10.5.0.0/16`` is used as an example; your subnet may be different.

.. code-block:: console

sshuttle -r <IP_OF_JUJU_CONTROLLER> 10.5.0.0/16

.. toctree::
Comment thread
WizardBit marked this conversation as resolved.
:hidden:
:maxdepth: 2

usage
Loading