A 12-Factor charm for the gopkg.in versioned import-path service.

gopkg-k8s

A Juju charm deploying and managing gopkg.in on Kubernetes. gopkg.in is the service that gives Go programs stable, major-version-specific import paths such as gopkg.in/yaml.v2, resolving each one to the newest matching tag of a GitHub repository and serving it to the Go tool. It allows for deployment on many different Kubernetes platforms, from MicroK8s to Charmed Kubernetes to public cloud Kubernetes offerings.

Canonical maintains this charm to run the public gopkg.in service. The service writes the hostname it is configured with 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. Run your own copy to mirror gopkg.in inside a network that cannot reach it, or to offer versioned import paths for GitHub repositories under your own domain.

Like any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. For gopkg-k8s, this includes:

• Serving go-import metadata and package pages under the hostname you configure
• Relaying Git transfers from GitHub to the Go tool
• Ingress integration for external HTTP access
• Observability integrations: Prometheus metrics, Loki logs, a Grafana dashboard, and alert rules

For information about how to deploy, integrate, and manage this charm, see the official gopkg-k8s documentation.

Get started

You need a Juju 3.6 controller on a Kubernetes cloud. The tutorial sets one up on MicroK8s from a fresh machine. Deploy the published charm:

juju add-model gopkg-k8s
juju deploy gopkg-k8s --channel latest/edge

The service is reachable only inside the cluster until an ingress charm publishes it. Deploy the NGINX ingress integrator, integrate it, and give both applications the same hostname:

juju deploy nginx-ingress-integrator --channel latest/stable --trust
juju integrate nginx-ingress-integrator gopkg-k8s
juju config nginx-ingress-integrator service-hostname=gopkg.example.com \
  path-routes=/ rewrite-enabled=false
juju config gopkg-k8s hostname=gopkg.example.com

juju status reports both applications as active when the deployment is ready.

Basic operations

Configure the hostname

The hostname option is the name the service writes into go-import metadata and package links. It must be the name that clients use, so change it together with the ingress hostname:

juju config nginx-ingress-integrator service-hostname=go.example.com
juju config gopkg-k8s hostname=go.example.com

See Configure the hostname and check go-import metadata.

Serve metrics on a separate port

By default the Prometheus metrics share the application port. To keep them off the port that ingress publishes:

juju config gopkg-k8s metrics-port=9102

See Integrate with the Canonical Observability Stack.

You can check out the full list of configuration options and actions on Charmhub.

Integrations

This charm can be integrated with other Juju charms and services:

• NGINX ingress integrator over ingress (interface ingress): routes external HTTP traffic to the service. Required to reach the service from outside the cluster.
• Loki over logging (interface loki_push_api): receives the service's JSON logs and its Loki alert rules.
• Prometheus over metrics-endpoint (interface prometheus_scrape): scrapes the service's metrics and loads its alert rules.
• Grafana over grafana-dashboard (interface grafana_dashboard): receives the gopkg Overview and Go Operator dashboards.

You can find the full list of integrations here.

Learn more

• Read more
• Developer documentation: endpoints, metrics, logs, and alert rules, for charms that integrate with this one
• Official webpage: the public gopkg.in service and its URL and version rules
• Troubleshooting

Project and community

• Issues
• Contributing
• Security policy
• Matrix

Licensing and trademark

The charm and the gopkg.in service it operates are distributed under the BSD-2-Clause licence. gopkg.in was created by Gustavo Niemeyer, whose copyright notice is retained.