juju/charm

Parsing and testing Juju charms

Juju is an open source application orchestration engine that enables any application operation (deployment, integration, lifecycle management) on any infrastructure (Kubernetes or otherwise) at any scale (development or production) in the same easy way (typically, one line of code), through special operators called ‘charms’.

👉	Juju	Learn how to quickly deploy, integrate, and manage charms on any cloud with Juju. It's as simple as juju deploy foo, juju integrate foo bar, ..., on any cloud.
	Charmhub	Sample our existing charms on Charmhub. A charm can be a cluster (OpenStack, Kubernetes), a data platform (PostgreSQL, MongoDB, etc.), an observability stack (Canonical Observability Stack), an MLOps solution (Kubeflow), and so much more.
	Charm SDK	Write your own charm! Juju is written in Go, but our SDK supports easy charm development in Python.

Give it a try!

Let's use Juju to deploy, configure, and integrate some Kubernetes charms:

Set up

You will need a cloud and Juju. The quickest way is to use a Multipass VM launched with the charm-dev blueprint.

Install Multipass: Linux | macOS | Windows. On Linux:

sudo snap install multipass

Use Multipass to launch an Ubuntu VM with the charm-dev blueprint:

multipass launch --cpus 4 --memory 8G --disk 30G --name tutorial-vm charm-dev 

Open a shell into the VM:

multipass shell tutorial-vm

Verify that you have Juju and two localhost clouds:

juju clouds

Bootstrap a Juju controller into the MicroK8s cloud:

juju bootstrap microk8s tutorial-controller

Add a workspace, or 'model':

juju add-model tutorial-model

Deploy, configure, and integrate a few things

Deploy Mattermost:

juju deploy mattermost-k8s

See more: Charmhub | mattermost-k8s

Deploy PostgreSQL:

juju deploy postgresql-k8s --channel 14/stable --trust

See more: Charmhub | postgresql-k8s

Enable security in your PostgreSQL deployment:

juju deploy tls-certificates-operator
juju config tls-certificates-operator generate-self-signed-certificates="true" ca-common-name="Test CA"
juju integrate postgresql-k8s tls-certificates-operator

Integrate Mattermost with PostgreSQL:

juju integrate mattermost-k8s postgresql-k8s:db

Watch your deployment come to life:

juju status --watch 1s

(Press Ctrl-C to quit. Drop the --watch 1s flag to get the status statically. Use the --relations flag to view more information about your integrations.)

Test your deployment

When everything is in active or idle status, note the IP address and port of Mattermost and pass them to curl:

curl <IP address>:<port>/api/v4/system/ping

You should see the output below:

{"AndroidLatestVersion":"","AndroidMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"}

Congratulations!

You now have a Kubernetes deployment consisting of a Mattermost backed by PosgreSQL with TLS-encrypted traffic!

Clean up

Delete your Multipass VM:

multipass delete --purge tutorial-vm

Uninstall Multipass: Linux | macOS | Windows. On Linux:

snap remove multipass

Next steps

Learn more

• Read our user docs
• Read our developer docs

Chat with us

Read our Code of conduct and:

• Join our chat: Matrix
• Join our forum: Discourse

File an issue

• Report a Juju bug on Launchpad
• Raise a general https://juju.is/docs documentation issue on Github | juju/docs

Make your mark

• Read our documentation contributor guidelines and help improve a doc
• Read our codebase contributor guidelines and help improve the codebase

charm's Issues

Stop removing all hidden files

currently, charm strips all hidden files from a charm payload but this is removing valuable information that's not related to VCS.

This strips files, like .build.manifest, which are used to record the layers in the built charm artifact.

Charm build: uncaught exception with broken YAML file should report error to user

If there's a problem parsing a yaml file as part of the charm, I get a python stack trace showing that there's a problem with the way pyyaml is used rather than an error explaining that a yaml file is broken.

$ charm version
charm 2.2.2
charm-tools 2.1.2

layer.yaml (note that that is a period between 'layer:basic' and 'layer:snap', not a comma):

includes: ['layer:basic'. 'layer:snap']
repo: https://github.com/...
options:
    basic:
        packages: ['python3-pip']
    snap:
        juju:
            classic: true

What I get:

$ charm build
build: Composing into /home/makyo/work/charms
build: Destination charm directory: /home/makyo/work/charms/trusty/...
Traceback (most recent call last):
  File "/snap/charm/17/bin/charm-build", line 11, in <module>
    load_entry_point('charm-tools==2.1.2', 'console_scripts', 'charm-build')()
  File "/snap/charm/17/lib/python2.7/site-packages/charmtools/build/builder.py", line 679, in main
    build()
  File "/snap/charm/17/lib/python2.7/site-packages/charmtools/build/builder.py", line 521, in __call__
    self.validate()
  File "/snap/charm/17/lib/python2.7/site-packages/charmtools/build/builder.py", line 478, in validate
    self._validate_charm_repo()
  File "/snap/charm/17/lib/python2.7/site-packages/charmtools/build/builder.py", line 506, in _validate_charm_repo
    if 'repo' not in self.top_layer.config:
  File "/snap/charm/17/lib/python2.7/site-packages/charmtools/build/builder.py", line 139, in top_layer
    self._top_layer = Layer(self.charm, self.deps).fetch()
  File "/snap/charm/17/lib/python2.7/site-packages/charmtools/build/builder.py", line 103, in fetch
    self._name = self.config.name
  File "/snap/charm/17/lib/python2.7/site-packages/charmtools/build/builder.py", line 45, in config
    self._config.configure(self.config_file)
  File "/snap/charm/17/lib/python2.7/site-packages/charmtools/build/config.py", line 56, in configure
    except yaml.parser.ParserError:
AttributeError: 'module' object has no attribute 'parser'

What I expect: an error telling me my layer.yaml file is borked (I think pyyaml should provide a reason why).

`charm build` - no such option: -d

Hitting this when running charm build https://paste.ubuntu.com/p/PmTBcjN86j/ using apt installed
charm package.

$ charm version
charm 2.1.1-0ubuntu1
charm-tools 2.1.2

Juju support for k3s distribution

Hello!

Is there any documentation regarding the installation of juju and its support for installing charm kubeflow on K3s cluster?
I look forward for your answers.
Regards,
Florin

Charm build: Leaking exception when charms begin with a number

metadata.yaml:

name: 1605096
summary: Dummy charm to reproduce bug 1605096.
maintainer: Katherine Cox-Buday <[email protected]>
description: |
  N/A
tags:
  - debug
series:
  - trusty
  - xenial
resources:
  foo:
    type: file
    filename: foo.txt
    description: Debug resource.

16:08> charm build
build: Composing into /home/kate/workspace/charm-1605096
Traceback (most recent call last):
  File "/usr/bin/charm-build", line 9, in <module>
    load_entry_point('charm-tools==1.11.2', 'console_scripts', 'charm-build')()
  File "/usr/lib/python2.7/dist-packages/charmtools/build/__init__.py", line 579, in main
    build()
  File "/usr/lib/python2.7/dist-packages/charmtools/build/__init__.py", line 461, in __call__
    self.find_or_create_repo()
  File "/usr/lib/python2.7/dist-packages/charmtools/build/__init__.py", line 198, in find_or_create_repo
    self.create_repo()
  File "/usr/lib/python2.7/dist-packages/charmtools/build/__init__.py", line 179, in create_repo
    self.target_dir = (self.repo / self.name)
  File "/usr/lib/python2.7/dist-packages/path.py", line 237, in __div__
    return self._next_class(self.module.join(self, rel))
  File "/usr/lib/python2.7/posixpath.py", line 68, in join
    if b.startswith('/'):
AttributeError: 'int' object has no attribute 'startswith'

Move systems to juju

[PACKAGING] Charm snap looks at wrong directory for git-core templates

I have installed the charm snap package.

When you run the following, you get a warning that warning: templates not found /snap/charm/609/share/git-core/templates.

$ charm create layer-example
INFO: Using default charm template (reactive-python). To select a different template, use the -t option.
INFO: Generating charm for layer-example in ./layer-example
INFO: No layer-example in apt cache; creating an empty charm instead.
Cloning into '/tmp/tmpsynyg40p'...
warning: templates not found /snap/charm/609/share/git-core/templates
remote: Enumerating objects: 32, done.
remote: Total 32 (delta 0), reused 0 (delta 0), pack-reused 32
Unpacking objects: 100% (32/32), done.
$

There is a missing /usr/ there. The following

/snap/charm/609/share/git-core/templates/

should be

/snap/charm/609/usr/share/git-core/templates/

Declared series should be checked for consistency

When a charm declares what series are supported, these should be checked to ensure they all belong to the same OS. It is not allowed for a charm to say it supports xenial and win10 for example.

json schemas for yaml files

metadata.yaml, actions.yaml and config.yaml would be much easier to write with auto completion, and charm authors would encounter less runtime errors with auto validation.

I created a json schema for metadata.yaml based on the Charm Metadata v2 post by @hpidcock and I really like the autocompletion + validation IDEs offer once you have a schema (I tested the schema using vscode + yaml extension).

• Validation could be done as part of charmcraft build (@facundobatista)
• Auto completion could be achieved by pointing the IDE to the json schema locally, and eventually, perhaps, via the schema store.

Schema draft: metadata-schema.json

supported-series metadata key name provides a poor user experience

I decided to open an issue instead of commenting on an already closed pull req #155. Not sure why this was changed given series already existed, was not being used, and conveys accurately what the field is designed for given the scope of the file. This feels tantamount to renaming the name field to charm-name. Before v6 moves into stable I'd like to discuss and hopefully reverse this decision.

Stacktrace on `charm create`

When I try to create a new charm with the snap version of charm, I get the following stacktrace on both cosmic and a clean xenial container. This same command worked as recently as a few days ago but is now failing

# charm create $charm_name
INFO: Using default charm template (reactive-python). To select a different template, use the -t option.
INFO: Generating charm for $charm_name in ./$charm_name
INFO: No $charm_name in apt cache; creating an empty charm instead.
Cloning into '/tmp/tmprs4mlcm_'...
warning: templates not found /snap/charm/158/share/git-core/templates
remote: Counting objects: 32, done.
remote: Total 32 (delta 0), reused 0 (delta 0), pack-reused 31
Unpacking objects: 100% (32/32), done.
Checking connectivity... done.
Traceback (most recent call last):
  File "/snap/charm/158/bin/charm-create", line 9, in <module>
    load_entry_point('charm-tools==2.2.4', 'console_scripts', 'charm-create')()
  File "/snap/charm/158/lib/python3.5/site-packages/charmtools/create.py", line 98, in main
    generator.create_charm()
  File "/snap/charm/158/lib/python3.5/site-packages/charmtools/generators/generator.py", line 93, in create_charm
    self.plugin.create_charm(user_config, tempdir)
  File "/snap/charm/158/lib/python3.5/site-packages/charmtools/templates/reactive_python/template.py", line 53, in create_charm
    self._template_file(config, path.join(root, outfile))
  File "/snap/charm/158/lib/python3.5/site-packages/charmtools/templates/reactive_python/template.py", line 64, in _template_file
    o.write(str(t))
  File "/snap/charm/158/usr/lib/python3.5/tempfile.py", line 622, in func_wrapper
    return func(*args, **kwargs)
TypeError: a bytes-like object is required, not 'str'

Remove Relation.Optional

This is a field in the metadata.yaml that doesn't actually do anything and isn't used by juju.

Apparently all relations are optional.

We should either:

• Remove this field if we can
• Allow it when parsing for backwards compatibility but remove it from the struct at the next API version.
• At the very least, add a TODO comment that this field is useless.

Or, educate me if I'm wrong.

revision file is empty in case of power loss/reset

In the case of a power loss or forced reset, the revision file is either empty or filled with \0. This mostly happens on Windows systems where disk cache and file buffers are enabled.

To get around this, we need to call Sync() on the file handle. This should be done on any important files that might prevent the unit from recovering.

update-status charm hook usage

Can somebody explain to me how to use the update-status hook? If I try to register it with r.RegisterHook it says invalid hook name "update-status".

Much appreciated.

Promulgating with charm un-promulgates previous charm

We noticed in the case with postgresql and ghost that when we promulgate new layer'ed charm for a given series, say Xenial previous series of the promulgated charm are un-promulgated.

For example, when we promulgated xenial/ghost, the store un-promulgated precise/ghost.

MockCharmStore.With{AuthAttrs,TestMode,DefaultSeries} are setters

func (s *MockCharmStore) WithAuthAttrs(auth string) charm.Repository {
    s.AuthAttrs = auth
    return s
}

func (s *MockCharmStore) WithTestMode(testMode bool) charm.Repository {
    s.TestMode = testMode
    return s
}

func (s *MockCharmStore) WithDefaultSeries(series string) charm.Repository {
    s.DefaultSeries = series
    return s
}

The following methods appear to return a copy of their receiver with a particular testing setting specified. However they do not, they modify their receiver and return themselves, not a copy.

This is bad for several reasons, none the least it produces a race condition as there is no synchronisation for these actions.