diff --git a/docs/developing/index.md b/docs/developing/index.md index efcc0212..51db92ed 100644 --- a/docs/developing/index.md +++ b/docs/developing/index.md @@ -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 @@ -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