# Charmcraft is for Kubernetes and machine operator developers

Charmcraft supports Kubernetes and machine operator development.

Charmcraft enables collaboration between charmed operator developers, and
publication on [Charmhub](https://charmhub.io/), home of the Charmed Operator
Collection.

Use `charmcraft` to:

- Init a new charmed operator file structure
- Build your operator into a charmed operator for distribution
- Register your charmed operator name on Charmhub
- Upload your charmed operators to Charmhub
- Release your charmed operators into channels

You can use charmcraft with operators written in any language but we
recommend the [Python Operator Framework on
Github](https://github.com/canonical/operator) which is also [on
PyPI](https://pypi.org/project/ops/) for ease of development and
collaboration.

Charmcraft and the Charmed Operator Framework extend the operator pattern
beyond Kubernetes or machine deployments with [universal
operators](https://juju.is/universal-operators) that drive Linux and
Windows apps. The universal operator pattern is very exciting for
multi-cloud application management.


## Install

The recommended way to install `charmcraft` is from the stable channel with

    sudo snap install charmcraft --classic

There are multiple channels other than `stable`. See the full list with
`snap info charmcraft`. We recommend either `latest/stable` or `latest/beta`
for everyday charming. With the snap you will always be up to date as
Charmhub services and APIs evolve.

You can also install `charmcraft` from PyPI, but some system packages 
(`libffi-dev`, `libapt-pkg-dev` and `libssl-dev`) and a Python package 
need to be installed first (`python-apt`). For the later in Ubuntu 
systems you need to check the 
[Python APT library page](https://launchpad.net/ubuntu/+source/python-apt) 
and choose the source file that matches your system (e.g. for Impish 
it's `python-apt_2.2.1.tar.xz`). So the instructions would be:

    $ sudo apt install -y libffi-dev libapt-pkg-dev libssl-dev
    $ python3 -m venv env
    $ source env/bin/activate
    (env)$ pip install https://launchpad.net/ubuntu/+archive/primary/+sourcefiles/python-apt/2.2.1/python-apt_2.2.1.tar.xz
    (env)$ pip install charmcraft


## Initialize a charm operator package file structure

Use `charmcraft init` to create a new template charm operator file tree:

```bash
$ mkdir my-new-charm; cd my-new-charm
$ charmcraft init
Charm operator package file and directory tree initialized.

Now edit the following package files to provide fundamental charm metadata and other information:

metadata.yaml
config.yaml
src/charm.py
README.md
```

You will now have all the essential files for a charmed operator, including
the actual `src/charm.py` skeleton and various items of metadata. Charmcraft
assumes you want to work in Python so it will add `requirements.txt` with
the Python operator framework `ops`, and other conventional development
support files.

## Build your charm

With a correct `metadata.yaml` and with `ops` in `requirements.txt` you can
build a charmed operator with:

```text
$ charmcraft pack
Created 'test-charm.charm'.
```

`charmcraft pack` will fetch additional files into the tree from PyPI based
on `requirements.txt` and will compile modules using a virtualenv.

The charmed operator is just a zipfile with metadata and the operator code
itself:

```text
$ unzip -l test-charm.charm
Archive:  test-charm.charm
  Length      Date    Time    Name
---------  ---------- -----   ----
      221  2020-11-15 08:10   metadata.yaml
[...]
    25304  2020-11-15 08:14   venv/yaml/__pycache__/scanner.cpython-38.pyc
---------                     -------
   812617                     84 files
```

Now, if you have a Kubernetes cluster with the Juju OLM accessible you can issue
`juju deploy ./my-new-charm.charm --resource httpbin-image=kennethreitz/httpbin`.
For classic machine deployments you can issue `juju deploy ./my-new-charm.charm`.
You do not need to publish your operator on Charmhub, you can pass the charmed
operator file around directly to users, or for CI/CD purposes.

## Charmhub login and charm name reservations

[Charmhub](https://charmhub.io/) is the world's largest repository of
operators. It makes it easy to share and collaborate on operators. The
community are interested in operators for a very wide range of purposes,
including infrastructure-as-code and legacy application management, and of
course Kubernetes operators.

Use `charmcraft login` and `charmcraft logout` to sign into Charmhub.

## Charmhub name registration

You can register operator names in Charmhub with `charmcraft register <name>`.
Many common names have been reserved, you are encouraged to discuss your
interest in leading or collaborating on a charmed operator in
[Charmhub Discourse](https://discourse.charmhub.io/).

Charmhub naming policy is the principle of least surprise - a well-known
name should map to an operator that most people would expect to get for that
name.

Operators in Charmhub can be renamed as needed, so feel free to register a
temporary name, such as <username>-<charmname> as a placeholder.

## Operator upload and release

Charmhub operators are published in channels, like:

```text
latest/stable
latest/candidate
latest/beta
latest/edge
1.3/beta
1.3/edge
1.2/stable
1.2/candidate
1.0/stable
```

Use `charmcraft upload` to get a new revision number for your freshly built
charmed operator, and `charmcraft release` to release a revision into any
particular channel for your users.
