Skip to content
This repository has been archived by the owner on Aug 8, 2024. It is now read-only.

Commit

Permalink
Clarify dev environment usage in docs (azimuth-cloud#162)
Browse files Browse the repository at this point in the history 
* Clarify dev environment usage in docs

* Add tip for producing unique values
  • Loading branch information
@mkjpryor
mkjpryor authored Jul 11, 2024
1 parent b958d7b commit 3ee7778
Showing 1 changed file with 72 additions and 40 deletions.
112 changes: 72 additions & 40 deletions docs/developing/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,58 +4,52 @@ An Azimuth deployment consists of several interdependent components, some of whi
Azimuth-specific and some of which are third-party components. Plugging code under
development into such a system can be tricky, making development difficult and slow.

## Developing Azimuth components

Azimuth has a number of components, mostly written in Python:
## Deploying a dev instance

* [Azimuth API and UI](https://github.com/stackhpc/azimuth) - user-facing API and UI
* [Azimuth CaaS operator](https://github.com/stackhpc/azimuth-caas-operator) - Kubernetes operator implementing CaaS functionality
* [Azimuth CAPI operator](https://github.com/stackhpc/azimuth-capi-operator) - Kubernetes operator implementing Kubernetes and Kubernetes App functionality
* [Azimuth identity operator](https://github.com/stackhpc/azimuth-identity-operator) - Kubernetes operator implementing platform identity
* [Zenith](https://github.com/stackhpc/zenith) - secure, tunnelling application proxy used to expose platform services
* [Cluster API addon provider](https://github.com/stackhpc/cluster-api-addon-provider) - addons for Cluster API clusters
* [Cluster API janitor for OpenStack](https://github.com/stackhpc/cluster-api-janitor-openstack) - resource cleanup for Cluster API clusters on OpenStack clouds
In order to develop Azimuth, you first need a running Azimuth instance.

It is useful to develop these components in the context of a running Azimuth installation,
as they have dependencies on each other.
Each developer should have their own independent instance of Azimuth for development,
as during development they will make changes to the running Azimuth components that may
conflict with or break things for others.

To enable this, Azimuth uses [Tilt](https://tilt.dev/) to provide a developer environment
where code under development is automatically built and injected into a live system that
you can interact with. Tilt provides a dashboard that can be used to drill down into
build failures and the logs of the components under development.
### Creating a dev environment

![Azimuth in Tilt](tilt-interface.png)
Azimuth supports using a single [configuration environment](../environments.md) to deploy multiple
independent Azimuth instances. When
[activating an environment](../deployment/#activating-an-environment), a unique instance name
can be given as a second argument to the `activate` script, e.g.:

### Prerequisites

In order to use Tilt to develop Azimuth, the following tools must be available on your
development machine (in addition to those required to install Azimuth itself):

* The [Tilt CLI](https://docs.tilt.dev/install.html)
* A `docker` command, e.g. [Docker Desktop](https://docs.docker.com/desktop/)
* The [kubectl command](https://kubernetes.io/docs/tasks/tools/#kubectl)
* The [Helm CLI](https://helm.sh/docs/intro/install/)
```bash
# Activating an environment with a unique instance name
source ./bin/activate my-environment jbloggs
```

For developing the Azimuth UI, the following are also required:
In order for an environment to be used in this way, it must be specially prepared to be more
dynamic than an environment that you would use for staging or production. In particular, only
[single node deployments](../configuration/02-deployment-method.md#single-node) are usable in
this way, as HA deployments do not support dynamically allocating a floating IP for the ingress
controller.

* [node.js](https://nodejs.org)
* The [Yarn Classic](https://classic.yarnpkg.com/lang/en/docs/install/) package manager
It is recommended that you create an environment in your Azimuth configuration repository
for doing Azimuth development on your cloud. This environment should include any site-specific
customisations that are required, usually by building on a
[site mixin](../environments.md#using-mixin-environments). The
[demo environment](https://github.com/stackhpc/azimuth-config/tree/devel/environments/demo)
is a good starting point for this, as it is designed to be flexible and dynamic.

### Deploying a dev instance
!!! tip "Producing unique values in your Azimuth configuration"

To use Tilt for developing Azimuth components, you first need a running Azimuth instance.

Each developer should have their own independent instance of Azimuth as Tilt will make
changes to the running Azimuth components, based on the code under development, that may
disrupt or break things for others.
The Ansible variable `azimuth_environment` contains the unique instance name, and
can be used in other variables in your configuration where a unique value is required
for each developer environment.

!!! tip
!!! warning "Developers should use their own application credential"

A single node deployment, e.g. a [demo deployment](../try.md), is sufficient for developing
the Azimuth components.
You should not include an application credential in your development environment.
Instead, each developer can use their own application credential as described in the
next section.

You may wish to maintain a [development environment](../environments.md) containing
site-specific customisations.
### Using the dev environment

The following instructions assume that your Azimuth configuration contains a developer environment
called `dev`. It is assumed that you have your Azimuth configuration checked out and that you have
Expand All @@ -81,6 +75,44 @@ ansible-galaxy install -f -r requirements.yml
ansible-playbook stackhpc.azimuth_ops.provision
```

## Developing Azimuth components

Azimuth has a number of components, mostly written in Python:

* [Azimuth API and UI](https://github.com/stackhpc/azimuth) - user-facing API and UI
* [Azimuth CaaS operator](https://github.com/stackhpc/azimuth-caas-operator) - Kubernetes operator implementing CaaS functionality
* [Azimuth CAPI operator](https://github.com/stackhpc/azimuth-capi-operator) - Kubernetes operator implementing Kubernetes and Kubernetes App functionality
* [Azimuth identity operator](https://github.com/stackhpc/azimuth-identity-operator) - Kubernetes operator implementing platform identity
* [Azimuth schedule operator](https://github.com/stackhpc/azimuth-schedule-operator) - Kubernetes operator implementing platform scheduling
* [Zenith](https://github.com/stackhpc/zenith) - secure, tunnelling application proxy used to expose platform services
* [Cluster API addon provider](https://github.com/stackhpc/cluster-api-addon-provider) - addons for Cluster API clusters
* [Cluster API janitor for OpenStack](https://github.com/stackhpc/cluster-api-janitor-openstack) - resource cleanup for Cluster API clusters on OpenStack clouds

It is useful to develop these components in the context of a running Azimuth installation,
as they have dependencies on each other.

To enable this, Azimuth uses [Tilt](https://tilt.dev/) to provide a developer environment
where code under development is automatically built and injected into a live system that
you can interact with. Tilt provides a dashboard that can be used to drill down into
build failures and the logs of the components under development.

![Azimuth in Tilt](tilt-interface.png)

### Prerequisites

In order to use Tilt to develop Azimuth, the following tools must be available on your
development machine (in addition to those required to install Azimuth itself):

* The [Tilt CLI](https://docs.tilt.dev/install.html)
* A `docker` command, e.g. [Docker Desktop](https://docs.docker.com/desktop/)
* The [kubectl command](https://kubernetes.io/docs/tasks/tools/#kubectl)
* The [Helm CLI](https://helm.sh/docs/intro/install/)

For developing the Azimuth UI, the following are also required:

* [node.js](https://nodejs.org)
* The [Yarn Classic](https://classic.yarnpkg.com/lang/en/docs/install/) package manager

### Configuring a container registry

Azimuth's Tilt configuration looks for a file called `tilt-settings.yaml` that defines settings
Expand Down

0 comments on commit 3ee7778

Please sign in to comment.