github.com/juju/juju@v0.0.0-20240430160146-1752b71fcf00/doc/cross-platform-development.md (about)

     1  ## Introduction
     2  It's often common practice that a juju developer needs to test out new juju code
     3  on machines that are not the same operating system or architecture to that of
     4  their current host. Alternatively in this workflow it is common place to want to
     5  want to perform Juju upgrades.
     6  
     7  Examples of this would be:
     8  - ubuntu/amd64 -> ubuntu/s390x
     9  - ubuntu/amd64 -> centos/amd64
    10  - macos/amd64 -> ubuntu/amd64
    11  - macos/arm64 -> ubutnu/amd64
    12  
    13  Doing this has been difficult in the past but with changes to the juju `Makefile`
    14  we can now build simple streams for multiple platforms and versions.
    15  
    16  ## How it works
    17  ### Bootstrapping
    18  We start by telling the juju build systems that we would like a local simple
    19  streams repository created for a given set of Go style os/arch pairs. For this
    20  example we would like a simple stream of our development changes that have
    21  artifacts for `linux/amd64` and `linux/arm64`.
    22  
    23  The juju build system is going place artifacts in a simplestream directory. You
    24  can optionally specify where you would like this directory to be by exporting
    25  `JUJU_METADATA_SOURCE` in your environment or simply let the build system choose
    26  for you.
    27  
    28  ```bash
    29  export JUJU_METADATA_SOURCE=<local_simplestreams_path>
    30  ```
    31  
    32  This is created by running:
    33  ```bash
    34  AGENT_PACKAGE_PLATFORMS="linux/amd64 linux/arm64" make simplestreams
    35  ```
    36  This process will build all the juju agent binaries for the platforms specified
    37  above and package them into a simple streams repository.
    38  
    39  The end of the output for this `make` command will also provide the user with an
    40  `export` statement that the user should run to help the juju bootstrap command
    41  automatically find this local simple streams repository. Example output:
    42  ```bash
    43  export JUJU_METADATA_SOURCE="...."
    44  ```
    45  
    46  You can ignore the above export requirement if you have previously done this in
    47  a previous step.
    48  
    49  You can now bootstrap using this simple streams repository using the usual:
    50  ```bash
    51  juju bootstrap cloudx
    52  ```
    53  
    54  **Note:** You may need to specify additional `bootstrap-constrains` to help juju
    55  choose the correct architecture.
    56  
    57  ### Upgrading
    58  Often once we have a bootstrapped controller we want to upgrade the controller
    59  for testing or time reasons.
    60  
    61  To do this we now need to run the `make simplestreams` target again but this
    62  time we also want to supply the build system with a build number.
    63  ```bash
    64  JUJU_BUILD_NUMBER=1 AGENT_PACKAGE_PLATFORMS="linux/amd64 linux/arm64" make simplestreams
    65  ```
    66  
    67  **Note:** A key way to tell if this has worked is by looking at the output of
    68  the command to confirm the new version is being used.
    69  
    70  You will also be prompted to export the `JUJU_METADATA_SOURCE` again. This step
    71  can safely be ignored if previously done from a previous step.
    72  
    73  Next we need to get these new version artifacts on to the juju controller that
    74  we want to upgrade.
    75  
    76  ```bash
    77  juju sync-agent-binary --version=<version>
    78  ```
    79  **Where `<version>` is the Juju version we are upgrading to including the build
    80  number from above.**
    81  
    82  We can now perform the upgrade using:
    83  
    84  ```bash
    85  juju upgrade-controller --agent-version <version>
    86  ```
    87  **Where `<version>` is the Juju version we are upgrading to including the build
    88  number from above.**
    89  
    90  ## Current limitations & future changes
    91  - Does not support oci artifacts including upgrading of OCI deployed controllers 
    92    and agents.
    93  - Would like to integrate work by @hpidcock for a simplestreams server that
    94    continuously builds and updates.