JS Jujulib

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

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

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.

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

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	ActionPrunerV1.ts
Action	ActionV6.ts ActionV7.ts
Admin	AdminV3.ts
AgentLifeFlag	AgentLifeFlagV1.ts
AgentTools	AgentToolsV1.ts
Agent	AgentV2.ts AgentV3.ts
AllModelWatcher	AllModelWatcherV2.ts AllModelWatcherV3.ts AllModelWatcherV4.ts
AllWatcher	AllWatcherV1.ts AllWatcherV2.ts AllWatcherV3.ts
Annotations	AnnotationsV2.ts
ApplicationOffers	ApplicationOffersV2.ts ApplicationOffersV3.ts ApplicationOffersV4.ts ApplicationOffersV5.ts ApplicationOffersV6.ts
ApplicationScaler	ApplicationScalerV1.ts
Application	ApplicationV12.ts ApplicationV13.ts ApplicationV14.ts ApplicationV15.ts ApplicationV18.ts ApplicationV19.ts ApplicationV22.ts
Backups	BackupsV2.ts BackupsV3.ts
Block	BlockV2.ts
Bundle	BundleV1.ts BundleV4.ts BundleV5.ts BundleV6.ts BundleV8.ts
CAASAdmission	CAASAdmissionV1.ts
CAASAgent	CAASAgentV1.ts CAASAgentV2.ts
CAASApplicationProvisioner	CAASApplicationProvisionerV1.ts
CAASApplication	CAASApplicationV1.ts
CAASFirewallerEmbedded	CAASFirewallerEmbeddedV1.ts
CAASFirewallerSidecar	CAASFirewallerSidecarV1.ts
CAASFirewaller	CAASFirewallerV1.ts
CAASModelConfigManager	CAASModelConfigManagerV1.ts
CAASModelOperator	CAASModelOperatorV1.ts
CAASOperatorProvisioner	CAASOperatorProvisionerV1.ts
CAASOperatorUpgrader	CAASOperatorUpgraderV1.ts
CAASOperator	CAASOperatorV1.ts
CAASUnitProvisioner	CAASUnitProvisionerV1.ts CAASUnitProvisionerV2.ts
CharmDownloader	CharmDownloaderV1.ts
CharmHub	CharmHubV1.ts
CharmRevisionUpdater	CharmRevisionUpdaterV2.ts
Charms	CharmsV2.ts CharmsV4.ts CharmsV5.ts CharmsV6.ts CharmsV7.ts
Cleaner	CleanerV2.ts
Client	ClientV2.ts ClientV3.ts ClientV5.ts ClientV6.ts ClientV7.ts ClientV8.ts
Cloud	CloudV1.ts CloudV2.ts CloudV3.ts CloudV4.ts CloudV5.ts CloudV7.ts CloudV8.ts
Controller	ControllerV11.ts ControllerV12.ts ControllerV13.ts ControllerV14.ts ControllerV3.ts ControllerV4.ts ControllerV5.ts ControllerV6.ts ControllerV7.ts ControllerV8.ts ControllerV9.ts
CredentialManager	CredentialManagerV1.ts
CredentialValidator	CredentialValidatorV2.ts
CrossController	CrossControllerV1.ts
CrossModelRelations	CrossModelRelationsV2.ts
CrossModelSecrets	CrossModelSecretsV1.ts
Deployer	DeployerV1.ts
DiskManager	DiskManagerV2.ts
EntityWatcher	EntityWatcherV2.ts
EnvironUpgrader	EnvironUpgraderV1.ts
ExternalControllerUpdater	ExternalControllerUpdaterV1.ts
FanConfigurer	FanConfigurerV1.ts
FilesystemAttachmentsWatcher	FilesystemAttachmentsWatcherV2.ts
FirewallRules	FirewallRulesV1.ts
Firewaller	FirewallerV5.ts FirewallerV7.ts
HighAvailability	HighAvailabilityV2.ts HighAvailabilityV3.ts
HostKeyReporter	HostKeyReporterV1.ts
ImageManager	ImageManagerV2.ts
ImageMetadataManager	ImageMetadataManagerV1.ts
ImageMetadata	ImageMetadataV3.ts
InstanceMutater	InstanceMutaterV2.ts InstanceMutaterV3.ts
InstancePoller	InstancePollerV4.ts
KeyManager	KeyManagerV1.ts
KeyUpdater	KeyUpdaterV1.ts
LeadershipService	LeadershipServiceV2.ts
LifeFlag	LifeFlagV1.ts
LogForwarding	LogForwardingV1.ts
Logger	LoggerV1.ts
MachineActions	MachineActionsV1.ts
MachineManager	MachineManagerV10.ts MachineManagerV11.ts MachineManagerV6.ts MachineManagerV7.ts MachineManagerV9.ts
MachineUndertaker	MachineUndertakerV1.ts
Machiner	MachinerV4.ts MachinerV5.ts
MeterStatus	MeterStatusV2.ts
MetricsAdder	MetricsAdderV2.ts
MetricsDebug	MetricsDebugV2.ts
MetricsManager	MetricsManagerV1.ts
MigrationFlag	MigrationFlagV1.ts
MigrationMaster	MigrationMasterV2.ts MigrationMasterV3.ts
MigrationMinion	MigrationMinionV1.ts
MigrationStatusWatcher	MigrationStatusWatcherV1.ts
MigrationTarget	MigrationTargetV1.ts MigrationTargetV2.ts MigrationTargetV3.ts
ModelConfig	ModelConfigV2.ts ModelConfigV3.ts ModelConfigV4.ts
ModelGeneration	ModelGenerationV4.ts
ModelManager	ModelManagerV10.ts ModelManagerV11.ts ModelManagerV2.ts ModelManagerV3.ts ModelManagerV4.ts ModelManagerV5.ts ModelManagerV8.ts ModelManagerV9.ts
ModelSummaryWatcher	ModelSummaryWatcherV1.ts
ModelUpgrader	ModelUpgraderV1.ts ModelUpgraderV2.ts
NotifyWatcher	NotifyWatcherV1.ts
OfferStatusWatcher	OfferStatusWatcherV1.ts
PayloadsHookContext	PayloadsHookContextV1.ts
Payloads	PayloadsV1.ts
Pinger	PingerV1.ts
Provisioner	ProvisionerV11.ts
ProxyUpdater	ProxyUpdaterV2.ts
RaftLease	RaftLeaseV1.ts RaftLeaseV2.ts
Reboot	RebootV2.ts
RelationStatusWatcher	RelationStatusWatcherV1.ts
RelationUnitsWatcher	RelationUnitsWatcherV1.ts
RemoteRelationWatcher	RemoteRelationWatcherV1.ts
RemoteRelations	RemoteRelationsV2.ts
ResourcesHookContext	ResourcesHookContextV1.ts
Resources	ResourcesV1.ts ResourcesV2.ts ResourcesV3.ts
Resumer	ResumerV2.ts
RetryStrategy	RetryStrategyV1.ts
SecretBackendsManager	SecretBackendsManagerV1.ts
SecretBackendsRotateWatcher	SecretBackendsRotateWatcherV1.ts
SecretBackends	SecretBackendsV1.ts
SecretsDrain	SecretsDrainV1.ts
SecretsManager	SecretsManagerV1.ts SecretsManagerV2.ts
SecretsRevisionWatcher	SecretsRevisionWatcherV1.ts
SecretsRotationWatcher	SecretsRotationWatcherV1.ts
SecretsTriggerWatcher	SecretsTriggerWatcherV1.ts
Secrets	SecretsV1.ts SecretsV2.ts
Singular	SingularV2.ts
Spaces	SpacesV6.ts
SSHClient	SSHClientV2.ts SSHClientV3.ts SSHClientV4.ts SSHClientV5.ts
StatusHistory	StatusHistoryV2.ts
StorageProvisioner	StorageProvisionerV4.ts
Storage	StorageV6.ts StorageV7.ts
StringsWatcher	StringsWatcherV1.ts
Subnets	SubnetsV4.ts SubnetsV5.ts
Undertaker	UndertakerV1.ts
UnitAssigner	UnitAssignerV1.ts
Uniter	UniterV16.ts UniterV18.ts UniterV19.ts
UpgradeSeries	UpgradeSeriesV3.ts
UpgradeSteps	UpgradeStepsV2.ts
Upgrader	UpgraderV1.ts
UserManager	UserManagerV1.ts UserManagerV2.ts UserManagerV3.ts
UserSecretsDrain	UserSecretsDrainV1.ts
UserSecretsManager	UserSecretsManagerV1.ts
VolumeAttachmentPlansWatcher	VolumeAttachmentPlansWatcherV1.ts
VolumeAttachmentsWatcher	VolumeAttachmentsWatcherV2.ts

Library Maintenance

Updating Library Facades

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

First, open the file generator/schema/schema-history.json and add a new object with juju-version set to the version of Juju you want to support.

Set schema to a "raw" path on github for the schema file e.g. https://raw.githubusercontent.com/juju/juju/refs/tags/v3.6.14/apiserver/facades/schema.json (substituting the tag with the version number from above).

Set juju-git-sha to the sha for the release (go to the release page for the version you want to support e.g. https://github.com/juju/juju/releases/tag/v3.6.14 and the sha will be listed next to the tag).

To update the facades, run yarn regenerate-all-facades. This will generate the facades using the data from the schema-history.json file.

Finally, update CLIENT_VERSION in api/client.ts with the highest version of Juju that is supported by Jujulib.

Releasing to NPM

• Update the version number in package.json, respecting semver, create a PR and land it.
• Build package with yarn run build.
• Upgrade the Juju Dashboard to this version using yarn link and ensure that everything works as expected.
• Create a new release on GitHub, setting the tag and title to the version number from above and include any relevant changes in the release notes (use the 'Generate release notes' to show changes since the last release and create a full changelog link, but rewrite 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 with yarn install && yarn run build.
• Now you can publish to NPM with yarn npm publish --access public.