# gopkg charm

`gopkg-k8s` is a [Juju](https://canonical.com/juju) [charm](https://canonical.com/juju/docs/juju-cli/3.6/reference/charm/) that
operates the `gopkg.in` versioned Go import service on Kubernetes.

The service ships as a rock, a container image built with Rockcraft. Juju
deploys the charm, and the charm runs that image, configures the public
hostname the service advertises, and connects it to ingress. Like any Juju
charm, it supports repeatable deployment, configuration, integration, and
lifecycle management, on Kubernetes platforms from [MicroK8s](https://canonical.com/microk8s) for local development to [Charmed
Kubernetes](https://ubuntu.com/kubernetes) and public-cloud Kubernetes
offerings.

`gopkg.in` gives Go programs stable, major-version-specific import paths:
`gopkg.in/yaml.v2` resolves to the newest v2 tag of the `go-yaml/yaml`
repository. Canonical maintains this charm to run the public `gopkg.in`
service. The service writes the configured hostname into its
`go-import` metadata, so a deployment serves imports of that hostname, not
of `gopkg.in`: code that already imports `gopkg.in/...` keeps using the
public service. Operators use their own copy to mirror `gopkg.in` inside a network
that cannot reach it, or to offer versioned import paths for GitHub
repositories under their own domain.

## In this documentation

| **Get started**            | [Deploy and verify gopkg-k8s on Kubernetes](https://canonical.com/juju/docs/gopkg-charm/latest/tutorials/deploy-and-verify-on-kubernetes/index.html.md#deploy-and-verify-on-kubernetes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Deployment**             | [Platforms and prerequisites](https://canonical.com/juju/docs/gopkg-charm/latest/reference/platforms-and-prerequisites/index.html.md#platforms-and-prerequisites)<br/>| [Configure ingress](https://canonical.com/juju/docs/gopkg-charm/latest/how-to/configure-ingress/index.html.md#configure-ingress)<br/>| [Configure hostname](https://canonical.com/juju/docs/gopkg-charm/latest/how-to/configure-hostname-and-check-go-import/index.html.md#configure-hostname-and-check-go-import)<br/>| [Set up production DNS](https://canonical.com/juju/docs/gopkg-charm/latest/how-to/configure-ingress/index.html.md#configure-ingress-dns)<br/>| [Charm configuration](https://canonical.com/juju/docs/gopkg-charm/latest/reference/charm-configuration/index.html.md#charm-configuration)                                                                                                                         |
| **Operations**             | [Integrate with COS Lite](https://canonical.com/juju/docs/gopkg-charm/latest/how-to/integrate-with-cos/index.html.md#integrate-with-cos)<br/>| [Upgrade](https://canonical.com/juju/docs/gopkg-charm/latest/how-to/upgrade-the-charm/index.html.md#upgrade-the-charm)<br/>| [Troubleshoot deployment issues](https://canonical.com/juju/docs/gopkg-charm/latest/how-to/troubleshoot-deployment/index.html.md#troubleshoot-deployment)<br/>| [Integration endpoints](https://canonical.com/juju/docs/gopkg-charm/latest/reference/integrations/index.html.md#integrations)<br/>| [Metrics](https://canonical.com/juju/docs/gopkg-charm/latest/reference/integrations/index.html.md#integrations-metrics)<br/>| [Logs](https://canonical.com/juju/docs/gopkg-charm/latest/reference/integrations/index.html.md#integrations-logs)<br/>| [Alert rules](https://canonical.com/juju/docs/gopkg-charm/latest/reference/integrations/index.html.md#integrations-alert-rules) |
| **Versioned import paths** | [Why gopkg.in exists](https://canonical.com/juju/docs/gopkg-charm/latest/explanation/gopkg-service/index.html.md#gopkg-service-why)<br/>| [What the service does](https://canonical.com/juju/docs/gopkg-charm/latest/explanation/gopkg-service/index.html.md#gopkg-service-what-it-does)<br/>| [Fetch a module with the Go tool](https://canonical.com/juju/docs/gopkg-charm/latest/tutorials/deploy-and-verify-on-kubernetes/index.html.md#tutorial-fetch-module)<br/>| [How a deployment differs from gopkg.in](https://canonical.com/juju/docs/gopkg-charm/latest/explanation/gopkg-service/index.html.md#gopkg-service-differences)                                                                                                                                                                                                          |
| **Design**                 | [How a request reaches the workload](https://canonical.com/juju/docs/gopkg-charm/latest/explanation/ingress/index.html.md#ingress-request-path)<br/>| [The two hostname settings](https://canonical.com/juju/docs/gopkg-charm/latest/explanation/ingress/index.html.md#ingress-two-hostnames)<br/>| [How the charm runs the service](https://canonical.com/juju/docs/gopkg-charm/latest/explanation/gopkg-service/index.html.md#gopkg-service-what-the-charm-adds)                                                                                                                                                                                                                                                                                                    |
| **Security**               | [Enable HTTPS](https://canonical.com/juju/docs/gopkg-charm/latest/how-to/configure-ingress/index.html.md#configure-ingress-https)<br/>| [Where TLS terminates](https://canonical.com/juju/docs/gopkg-charm/latest/explanation/ingress/index.html.md#ingress-tls)<br/>| [Keep the metrics endpoint off the public hostname](https://canonical.com/juju/docs/gopkg-charm/latest/how-to/integrate-with-cos/index.html.md#cos-metrics-port)                                                                                                                                                                                                                                                                                                                                    |
| **Development**            | [Set up a development environment](https://canonical.com/juju/docs/gopkg-charm/latest/contribute/set-up-a-development-environment/index.html.md#set-up-a-development-environment)<br/>| [Improve the code](https://canonical.com/juju/docs/gopkg-charm/latest/contribute/improve-code/index.html.md#improve-code)<br/>| [Improve the documentation](https://canonical.com/juju/docs/gopkg-charm/latest/contribute/improve-documentation/index.html.md#improve-documentation)<br/>| [CI workflows](https://canonical.com/juju/docs/gopkg-charm/latest/contribute/ci-workflows/index.html.md#ci-workflows)<br/>| [Troubleshoot](https://canonical.com/juju/docs/gopkg-charm/latest/contribute/troubleshoot-development/index.html.md#troubleshoot-development)                                                                                                                                                   |

## How this documentation is organized

This documentation uses the [Diátaxis](https://diataxis.fr/) documentation
structure.

- The [Tutorial](https://canonical.com/juju/docs/gopkg-charm/latest/tutorials/index.html.md#tutorials) takes you step-by-step through a first
  deployment of `gopkg-k8s`.
- [How-to guides](https://canonical.com/juju/docs/gopkg-charm/latest/how-to/index.html.md#how-to-guides) cover practical tasks for configuring,
  operating, and maintaining your `gopkg-k8s` deployment.
- [Reference](https://canonical.com/juju/docs/gopkg-charm/latest/reference/index.html.md#reference) provides technical information to look up
  while you work, such as configuration options, integrations, and supported
  platforms.
- [Explanation](https://canonical.com/juju/docs/gopkg-charm/latest/explanation/index.html.md#explanation) includes background, context, and
  discussion of the concepts and design behind the charm.
- [Contribute](https://canonical.com/juju/docs/gopkg-charm/latest/contribute/index.html.md#contribute) guides developers who want to change the
  charm or its documentation.
- [Release notes](https://canonical.com/juju/docs/gopkg-charm/latest/release-notes/index.html.md#release-notes-index) hold the release history.

### Contributing to this documentation

Documentation is an important part of this project, and it takes the same
open source approach as the code. Community contributions, suggestions, and
constructive feedback are welcome; see [Contribute](https://canonical.com/juju/docs/gopkg-charm/latest/contribute/index.html.md#contribute) for how to get
started. If a topic you need is missing, please [file a bug](https://github.com/canonical/gopkg-charmed/issues).

## Project and community

`gopkg-k8s` is a member of the Ubuntu family. It is an open source
project that warmly welcomes community projects, contributions, suggestions,
fixes, and constructive feedback.

### Governance and policies

- [Code of conduct](https://ubuntu.com/community/docs/ethos/code-of-conduct)
- [Security policy](https://github.com/canonical/gopkg-charmed/blob/main/SECURITY.md)

### Get involved

- [Get support](https://discourse.charmhub.io/)
- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
- [Report an issue](https://github.com/canonical/gopkg-charmed/issues)
- [Contribute](https://canonical.com/juju/docs/gopkg-charm/latest/contribute/index.html.md#contribute)

Thinking about using `gopkg-k8s` for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)!