charmcraft


Namecharmcraft JSON
Version 2.5.2 PyPI version JSON
download
home_pagehttps://github.com/canonical/charmcraft
SummaryThe main tool to build, upload, and develop in general the Juju charms.
upload_time2023-12-01 18:08:20
maintainer
docs_urlNone
authorFacundo Batista
requires_python>=3
licenseApache-2.0
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/canonical/charmcraft",
    "name": "charmcraft",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3",
    "maintainer_email": "",
    "keywords": "",
    "author": "Facundo Batista",
    "author_email": "facundo.batista@canonical.com",
    "download_url": "https://files.pythonhosted.org/packages/88/30/88063d83fd81f1334a1c720d56ddd37adc4137350b87079438957b90bff3/charmcraft-2.5.2.tar.gz",
    "platform": null,
    "description": "# Charmcraft is for Kubernetes and machine operator developers\n\nCharmcraft supports Kubernetes and machine operator development.\n\nCharmcraft enables collaboration between charmed operator developers, and\npublication on [Charmhub](https://charmhub.io/), home of the Charmed Operator\nCollection.\n\nUse `charmcraft` to:\n\n- Init a new charmed operator file structure\n- Build your operator into a charmed operator for distribution\n- Register your charmed operator name on Charmhub\n- Upload your charmed operators to Charmhub\n- Release your charmed operators into channels\n\nYou can use charmcraft with operators written in any language but we\nrecommend the [Python Operator Framework on\nGithub](https://github.com/canonical/operator) which is also [on\nPyPI](https://pypi.org/project/ops/) for ease of development and\ncollaboration.\n\nCharmcraft and the Charmed Operator Framework extend the operator pattern\nbeyond Kubernetes or machine deployments with [universal\noperators](https://juju.is/universal-operators) that drive Linux and\nWindows apps. The universal operator pattern is very exciting for\nmulti-cloud application management.\n\n\n## Install\n\nThe recommended way to install `charmcraft` is from the stable channel with\n\n    sudo snap install charmcraft --classic\n\nThere are multiple channels other than `stable`. See the full list with\n`snap info charmcraft`. We recommend either `latest/stable` or `latest/beta`\nfor everyday charming. With the snap you will always be up to date as\nCharmhub services and APIs evolve.\n\nYou can also install `charmcraft` from PyPI, but some system packages \n(`libffi-dev`, `libapt-pkg-dev` and `libssl-dev`) and a Python package \nneed to be installed first (`python-apt`). For the later in Ubuntu \nsystems you need to check the \n[Python APT library page](https://launchpad.net/ubuntu/+source/python-apt) \nand choose the source file that matches your system (e.g. for Impish \nit's `python-apt_2.2.1.tar.xz`). So the instructions would be:\n\n    $ sudo apt install -y libffi-dev libapt-pkg-dev libssl-dev\n    $ python3 -m venv env\n    $ source env/bin/activate\n    (env)$ pip install https://launchpad.net/ubuntu/+archive/primary/+sourcefiles/python-apt/2.2.1/python-apt_2.2.1.tar.xz\n    (env)$ pip install charmcraft\n\n\n## Initialize a charm operator package file structure\n\nUse `charmcraft init` to create a new template charm operator file tree:\n\n```bash\n$ mkdir my-new-charm; cd my-new-charm\n$ charmcraft init\nCharm operator package file and directory tree initialized.\n\nNow edit the following package files to provide fundamental charm metadata and other information:\n\nmetadata.yaml\nconfig.yaml\nsrc/charm.py\nREADME.md\n```\n\nYou will now have all the essential files for a charmed operator, including\nthe actual `src/charm.py` skeleton and various items of metadata. Charmcraft\nassumes you want to work in Python so it will add `requirements.txt` with\nthe Python operator framework `ops`, and other conventional development\nsupport files.\n\n## Build your charm\n\nWith a correct `metadata.yaml` and with `ops` in `requirements.txt` you can\nbuild a charmed operator with:\n\n```text\n$ charmcraft pack\nCreated 'test-charm.charm'.\n```\n\n`charmcraft pack` will fetch additional files into the tree from PyPI based\non `requirements.txt` and will compile modules using a virtualenv.\n\nThe charmed operator is just a zipfile with metadata and the operator code\nitself:\n\n```text\n$ unzip -l test-charm.charm\nArchive:  test-charm.charm\n  Length      Date    Time    Name\n---------  ---------- -----   ----\n      221  2020-11-15 08:10   metadata.yaml\n[...]\n    25304  2020-11-15 08:14   venv/yaml/__pycache__/scanner.cpython-38.pyc\n---------                     -------\n   812617                     84 files\n```\n\nNow, if you have a Kubernetes cluster with the Juju OLM accessible you can issue\n`juju deploy ./my-new-charm.charm --resource httpbin-image=kennethreitz/httpbin`.\nFor classic machine deployments you can issue `juju deploy ./my-new-charm.charm`.\nYou do not need to publish your operator on Charmhub, you can pass the charmed\noperator file around directly to users, or for CI/CD purposes.\n\n## Charmhub login and charm name reservations\n\n[Charmhub](https://charmhub.io/) is the world's largest repository of\noperators. It makes it easy to share and collaborate on operators. The\ncommunity are interested in operators for a very wide range of purposes,\nincluding infrastructure-as-code and legacy application management, and of\ncourse Kubernetes operators.\n\nUse `charmcraft login` and `charmcraft logout` to sign into Charmhub.\n\n## Charmhub name registration\n\nYou can register operator names in Charmhub with `charmcraft register <name>`.\nMany common names have been reserved, you are encouraged to discuss your\ninterest in leading or collaborating on a charmed operator in\n[Charmhub Discourse](https://discourse.charmhub.io/).\n\nCharmhub naming policy is the principle of least surprise - a well-known\nname should map to an operator that most people would expect to get for that\nname.\n\nOperators in Charmhub can be renamed as needed, so feel free to register a\ntemporary name, such as <username>-<charmname> as a placeholder.\n\n## Operator upload and release\n\nCharmhub operators are published in channels, like:\n\n```text\nlatest/stable\nlatest/candidate\nlatest/beta\nlatest/edge\n1.3/beta\n1.3/edge\n1.2/stable\n1.2/candidate\n1.0/stable\n```\n\nUse `charmcraft upload` to get a new revision number for your freshly built\ncharmed operator, and `charmcraft release` to release a revision into any\nparticular channel for your users.\n",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": "The main tool to build, upload, and develop in general the Juju charms.",
    "version": "2.5.2",
    "project_urls": {
        "Homepage": "https://github.com/canonical/charmcraft"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "883088063d83fd81f1334a1c720d56ddd37adc4137350b87079438957b90bff3",
                "md5": "3b6021acd3ca8a6de03d16094532187c",
                "sha256": "874a95dc0d9a4d688625bf04eaa5a14921715425167412d5e0d89c158636e02e"
            },
            "downloads": -1,
            "filename": "charmcraft-2.5.2.tar.gz",
            "has_sig": false,
            "md5_digest": "3b6021acd3ca8a6de03d16094532187c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3",
            "size": 185392,
            "upload_time": "2023-12-01T18:08:20",
            "upload_time_iso_8601": "2023-12-01T18:08:20.318152Z",
            "url": "https://files.pythonhosted.org/packages/88/30/88063d83fd81f1334a1c720d56ddd37adc4137350b87079438957b90bff3/charmcraft-2.5.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-12-01 18:08:20",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "canonical",
    "github_project": "charmcraft",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [],
    "tox": true,
    "lcname": "charmcraft"
}
        
Elapsed time: 0.15376s