Skip to content

juju/js-libjuju

Repository files navigation

JS Jujulib

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

Getting Started

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

import { connect } from "@canonical/jujulib";

import Client from "@canonical/jujulib/dist/api/facades/client";
import ModelManager from "@canonical/jujulib/dist/api/facades/model-manager";

// Nodejs
// import WebSocket from "ws";

const serverURL = "ws://localhost:17070";
const credentials = {
  username: "admin",
  password: "test",
};

// Connect to the controller
const controller = await connect(`${serverURL}/api`, {
  facades: [ModelManager],
  wsclass: WebSocket,
});
let conn = await controller.login(credentials);

// Get the list of models
const modelManager = conn.facades.modelManager;
const response = await modelManager.listModels({
  tag: conn.info.user.identity,
});
const models = response["user-models"];
console.log("models:", models);

// Close the connection to the controller
conn.transport.close();

// Login to each model
for (const modelDetails of models) {
  const model = await connect(
    `${serverURL}/model/${modelDetails.model.uuid}/api`,
    {
      facades: [Client],
      wsclass: WebSocket,
    }
  );
  conn = await model.login(credentials);

  // Get the details of the model
  const client = conn.facades.client;
  console.log("model details:", await client.fullStatus());

  // Close the connection to the model
  conn.transport.close();
}

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

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.

The connect method returns a juju object which is used to log into the controller or model by providing a user/pass credentials or macaroons. See the various examples.

Client API Reference

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

Examples

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

Facade API Reference

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

Facade Versions
ActionPruner
Action
Admin
AgentLifeFlag
AgentTools
Agent
AllModelWatcher
AllWatcher
Annotations
ApplicationOffers
ApplicationScaler
Application
Backups
Block
Bundle
CAASAdmission
CAASAgent
CAASApplicationProvisioner
CAASApplication
CAASFirewallerEmbedded
CAASFirewallerSidecar
CAASFirewaller
CAASModelConfigManager
CAASModelOperator
CAASOperatorProvisioner
CAASOperatorUpgrader
CAASOperator
CAASUnitProvisioner
CharmDownloader
CharmHub
CharmRevisionUpdater
Charms
Cleaner
Client
Cloud
Controller
CredentialManager
CredentialValidator
CrossController
CrossModelRelations
CrossModelSecrets
Deployer
DiskManager
EntityWatcher
EnvironUpgrader
ExternalControllerUpdater
FanConfigurer
FilesystemAttachmentsWatcher
FirewallRules
Firewaller
HighAvailability
HostKeyReporter
ImageManager
ImageMetadataManager
ImageMetadata
InstanceMutater
InstancePoller
KeyManager
KeyUpdater
LeadershipService
LifeFlag
LogForwarding
Logger
MachineActions
MachineManager
MachineUndertaker
Machiner
MeterStatus
MetricsAdder
MetricsDebug
MetricsManager
MigrationFlag
MigrationMaster
MigrationMinion
MigrationStatusWatcher
MigrationTarget
ModelConfig
ModelGeneration
ModelManager
ModelSummaryWatcher
ModelUpgrader
NotifyWatcher
OfferStatusWatcher
PayloadsHookContext
Payloads
Pinger
Provisioner
ProxyUpdater
RaftLease
Reboot
RelationStatusWatcher
RelationUnitsWatcher
RemoteRelationWatcher
RemoteRelations
ResourcesHookContext
Resources
Resumer
RetryStrategy
SecretBackendsManager
SecretBackendsRotateWatcher
SecretBackends
SecretsDrain
SecretsManager
SecretsRevisionWatcher
SecretsRotationWatcher
SecretsTriggerWatcher
Secrets
Singular
Spaces
SSHClient
StatusHistory
StorageProvisioner
Storage
StringsWatcher
Subnets
Undertaker
UnitAssigner
Uniter
UpgradeSeries
UpgradeSteps
Upgrader
UserManager
UserSecretsDrain
UserSecretsManager
VolumeAttachmentPlansWatcher
VolumeAttachmentsWatcher

Library Maintenance

Updating Library Facades

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

To generate this schema you will need to clone the Juju repository and then run make rebuild-schema or go 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 are latest and all.

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

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

Finally, update CLIENT_VERSION in api/client.ts with the highest support version.

Releasing to NPM

  • Update the version number in package.json, respecting semver.
  • Run the tests with npm test.
  • Run the examples with node to ensure that everything works as expected.
  • Upgrade the Juju Dashboard to this version using npm link and ensure that everything works as expected.
  • Tag the version in the git repository with the version number from above.
  • npm publish.
  • Update the release notes in the repository.
  • Create a post on the Juju Discourse with information about the release.