Repository files navigation

This project provides a JavaScript API client library for interacting with the JujuWebSocket API.

• Getting Started
• Client API Reference
• Examples
• Facade API Reference
• Library Maintenance
  • Updating Library Facades
  • Releasing to NPM

To access the Juju API, a connection must be made to either a Jujucontroller or a Juju model.

import{connect}from"@canonical/jujulib";importClientfrom"@canonical/jujulib/dist/api/facades/client";importModelManagerfrom"@canonical/jujulib/dist/api/facades/model-manager";// Nodejs// import WebSocket from "ws";constserverURL="ws://localhost:17070";constcredentials={username:"admin",password:"test",};// Connect to the controllerconstcontroller=awaitconnect(`${serverURL}/api`,{facades:[ModelManager],wsclass:WebSocket,});letconn=awaitcontroller.login(credentials);// Get the list of modelsconstmodelManager=conn.facades.modelManager;constresponse=awaitmodelManager.listModels({tag:conn.info.user.identity,});constmodels=response["user-models"];console.log("models:",models);// Close the connection to the controllerconn.transport.close();// Login to each modelfor(constmodelDetailsofmodels){constmodel=awaitconnect(`${serverURL}/model/${modelDetails.model.uuid}/api`,{facades:[Client],wsclass:WebSocket,});conn=awaitmodel.login(credentials);// Get the details of the modelconstclient=conn.facades.client;console.log("model details:",awaitclient.fullStatus());// Close the connection to the modelconn.transport.close();}

In the code above, a connection is established to the provided controller API URL where the client declares interest in using the facadeModelManager, and we establish a new connection with each model API to get the full details using the facadeClient.

Note: Facades are used to supported different versions of juju, when multiple versions of the same facade are supported by the juju API (like the two client versions in the example), the most recent version supported by the server is made available to the client.

Theconnect method returns ajuju object which is used to log into the controller or model by providing a user/pass credentials ormacaroons. See thevarious examples.

Visit thefull API documentation for detailed information on the Client API.

We have a number of examples showing how to perform a few common tasks. Those can be found in theexamples folder.

• add-machine.js
• deploy.js
• login-with-bakery.js
• watch-all-models.js
• watch.js

Detailed Facade documentation is available as part of thefull API documentation or you can visit the facade source directly using the following links:

The Juju facade API files are generated from a supplied Juju schema.

To generate this schema you will need to clone theJuju repository and then runmake rebuild-schema orgo run github.com/juju/juju/generate/schemagen -admin-facades --facade-group=client,jimm ./apiserver/facades/schema.json to generate a schema file that contains the publicly available facades as well as the set of facades for JAAS. Other--facade-group options arelatest andall.

After generating a new schema runyarn store-schema ../path/to/juju which will store the updated schema and necessary meta data in this project.

To update the facades, runyarn generate-facades on this project. This will generate the facades using the locally stored schema, sha, and version the schema was generated from.

Finally, updateCLIENT_VERSION inapi/client.ts with the highest support version.

• Update the version number inpackage.json, respecting semver, create a PRand land it.
• Build package withyarn run build.
• Upgrade theJuju Dashboard to this version usingyarn link and ensure that everything works as expected.
• Create anew release onGitHub, setting the tag and title to the version number from above and includeany relevant changes in the release notes (use the 'Generate release notes' toshow changes since the last release and create a full changelog link, butrewrite the changes to help them make sense to consumers of the library).
• Clone a fresh copy of the repository:git clone git@github.com:juju/js-libjuju.git.
• Install the dependencies and build the package withyarn install && yarn run build.
• Now you can publish to NPM withyarn publish.