geryon

README

Geryon

/‘dʒɪəriən/
ge-re-on
noun

1. A mythological Greek monster. Like the :octocat:, it's not entirely clear how many legs Geryon had.
2. A GitHub App for Kubernetes clusters. Run it on your cluster to let others in your organization connect their repo to that cluster by installing the app.

Features

Namespace creation

Geryon will create a Kubernetes namespace named after each GitHub Repository it is installed on.

ImagePullCredentials for GitHub Package Registry

Namespaces created by Geryon include a Secret containing regularly-refreshed imagePullSecrets credentials to allow them to access Docker images pushed to the GitHub Package Registry. Namespaces' default ServiceAccount are also patched to refer these imagePullSecrets.

Installation

• Create a new GitHub App with the following settings:
  • Name: geryon-your-cluster-name-goes-here
  • Homepage URL: https://example.com/
  • Webhook URL: https://example.com/ (we'll come back in a minute to update if you choose to enable webhooks)
  • Webhook Secret: Generate a unique secret with openssl rand -base64 32 | tee webhook-secret
  • Permissions:
    • Repository metadata: Read-only
    • Packages: Read-only
• Generate and download a new key for your app. Copy it to private-key.pem
• Download kustomization.example.yaml and rename it to kustomization.yaml
• Update the APP_ID value to reflect the numeric ID of your GitHub app
• Create an Ingress resource at ingress.yaml as required by your Kubernetes provider
  • See this GKE example for reference
• Create a geryon namespace on your Kubernetes cluster: kubectl create ns geryon
• Apply geryon to your cluster: kubectl apply -k .
• Update your GitHub app's Webhook URL to the URL of your Ingress resource

Development

1. Create a GitHub App and generate a private key
2. Create .env:

PORT=8081
WEBHOOK_SECRET=asdf
APP_ID=30576
PRIVATE_KEY_FILE=geryon-dev.2019-05-12.private-key.pem
KUBECONFIG=/path/to/your/dev-cluster/.kube/config

1. Run the thing:

go build ./cmd/geryon && env $(cat .env | xargs) ./geryon

Documentation

Overview

Package geryon contains a GitHub App for Kubernetes clusters

It automatically creates namespaces for each GitHub Repository the app is installed on, and automatically syncs ImagePullSecrets for GitHub's Package Registry

Index

• Constants
• type Config
• type Geryon
  • func NewGeryon(config Config) (*Geryon, error)
  • func (g *Geryon) ResyncInstallationNamespaces()
  • func (g *Geryon) ResyncManagedNamespaces()
  • func (g *Geryon) Run(stopCh <-chan struct{}) error
  • func (g *Geryon) SyncNamespace(nameAndInstallationID string) error

Constants

const (
	// InstallationIDAnnotation is added to all namespaces created by geryon
	InstallationIDAnnotation = "urcomputeringpal.com/geryon-installation-id"

	// ImagePullSyncAnnotation is used to determine whether or not to sync secrets on a namespace
	ImagePullSyncAnnotation = "urcomputeringpal.com/geryon-sync-image-pull-secrets"

	// ImagePullSyncTimestampAnnotation is added to the secret and is updated when it is synced
	ImagePullSyncTimestampAnnotation = "urcomputeringpal.com/geryon-image-pull-secrets-sync-timestamp"

	// DockerSecretName is the name of the secret containing Docker credentials
	DockerSecretName = "github-package-registry"
)

Types

type Config

type Config struct {
	WebhookPort                int
	GitHubAppID                int
	GitHubAppPrivateKeyFile    string
	GithubAppWebHookSecret     string
	Kubeconfig                 string
	InstallationResyncInterval time.Duration
	NamespaceResyncInterval    time.Duration
	Threadiness                int
}

Config contains the configuration for a Geryon controller

type Geryon

type Geryon struct {
	GithubAppsClient       *github.Client
	KubernetesClient       *kubernetes.Clientset
	NamespaceInformerCache cache.Store

	Config Config
	// contains filtered or unexported fields
}

Geryon is a Kubernetes controller that keeps your cluster in sync with your GitHub account. At its core, it's a GitHub Client, a Kubernetes client, a work queue, and a bunch of workers.

func NewGeryon

func NewGeryon(config Config) (*Geryon, error)

NewGeryon creates a Geryon controller

func (*Geryon) ResyncInstallationNamespaces

func (g *Geryon) ResyncInstallationNamespaces()

ResyncInstallationNamespaces loads a list of Installations and Repositories from GitHub and queues up a call to SyncNamespace for each. Run calls this every Config.InstallationResyncInterval

func (*Geryon) ResyncManagedNamespaces

func (g *Geryon) ResyncManagedNamespaces()

ResyncManagedNamespaces loads a list of all namespaces that were created by Geryon and queues up a call to SyncNamespace for each every Config.NamespaceResyncInterval

func (*Geryon) Run

func (g *Geryon) Run(stopCh <-chan struct{}) error

Run takes one stop channel and coordinates all of our various workers

func (*Geryon) SyncNamespace

func (g *Geryon) SyncNamespace(nameAndInstallationID string) error

SyncNamespace ensures a Namespace exists for each Installation, and that it's default ServiceAccount has be configured with imagePullSecrets for the GitHub Package Registry