admin

README

admin

This directory contains the control-plane for multi-user, hosted deployments of Rill.

Running in development

1. Create a .env file at the root of the repo containing:

RILL_ADMIN_DATABASE_DRIVER=postgres
RILL_ADMIN_DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres
RILL_ADMIN_HTTP_PORT=8080
RILL_ADMIN_GRPC_PORT=9090
RILL_ADMIN_EXTERNAL_URL=http://localhost:8080
RILL_ADMIN_FRONTEND_URL=http://localhost:3000
RILL_ADMIN_ALLOWED_ORIGINS=*
# Hex-encoded comma-separated list of keys. For details: https://pkg.go.dev/github.com/gorilla/sessions#NewCookieStore
RILL_ADMIN_SESSION_KEY_PAIRS=7938b8c95ac90b3731c353076daeae8a,90c22a5a6c6b442afdb46855f95eb7d6
# Get these from https://auth0.com/ (or ask a team member)
RILL_ADMIN_AUTH_DOMAIN=gorillio-stage.auth0.com
RILL_ADMIN_AUTH_CLIENT_ID=
RILL_ADMIN_AUTH_CLIENT_SECRET=
# Get these from https://github.com/ (or ask a team member)
RILL_ADMIN_GITHUB_APP_ID=302634
RILL_ADMIN_GITHUB_APP_NAME=rill-cloud-dev
RILL_ADMIN_GITHUB_APP_PRIVATE_KEY=
RILL_ADMIN_GITHUB_APP_WEBHOOK_SECRET=

1. In a separate terminal, run Postgres in the background:

docker-compose -f admin/docker-compose.yml up 
# Data is persisted. To clear, run: docker-compose -f admin/docker-compose.yml down --volumes

1. Run the server:

go run ./cli admin start

1. Ping the server:

go run ./cli admin ping --base-url http://localhost:9090

You can now call the local admin server from the CLI by overriding the admin API URL. For example:

go run ./cli org create foo --api-url http://localhost:9090

Adding endpoints

We define our APIs using gRPC and use gRPC-Gateway to map the RPCs to a RESTful API. See proto/README.md for details.

To add a new endpoint:

1. Describe the endpoint in proto/rill/admin/v1/api.proto
2. Re-generate gRPC and OpenAPI interfaces by running make proto.generate
3. Copy the new handler signature from the AdminServiceServer interface in proto/gen/rill/admin/v1/api_grpc_pb.go
4. Paste the handler signature and implement it in a relevant file in admin/server/

Using the Github App in development

We use a Github App to listen to pushes on repositories connected to Rill to do automated deployments. The app has access to read contents and receives webhooks on git push.

Github relies on webhooks to deliver information about new connections, pushes, etc. In development, in order for webhooks to be received on localhost, we use this proxy service: https://github.com/probot/smee.io.

Setup instructions:

1. Install Smee

npm install --global smee-client

1. Run it (get IDENTIFIER from the Github App info or a team member):

smee --port 8080 --path /github/webhook --url https://smee.io/IDENTIFIER

CLI login/logout

For trying out CLI login add api-url parameter to point to local admin HTTP server like this:

go run ./cli auth login --api-url http://localhost:8080/

For trying out CLI logout add api-url parameter to point to local admin gRPC server like this:

go run ./cli auth logout --api-url http://localhost:9090/

Documentation

Index

• Constants
• type AuthToken
• type Options
• type Service
  • func New(opts *Options, logger *zap.Logger, issuer *auth.Issuer) (*Service, error)
  • func (s *Service) Close() error
  • func (s *Service) CreateOrUpdateUser(ctx context.Context, email, name, photoURL string) (*database.User, error)
  • func (s *Service) CreateProject(ctx context.Context, proj *database.Project) (*database.Project, error)
  • func (s *Service) GetUserGithubInstallation(ctx context.Context, userID, githubURL string) (int64, bool, error)
  • func (s *Service) IssueAuthCode(ctx context.Context, clientID string) (*database.AuthCode, error)
  • func (s *Service) IssueUserAuthToken(ctx context.Context, userID, clientID, displayName string) (AuthToken, error)
  • func (s *Service) LookupGithubRepo(ctx context.Context, installationID int64, githubURL string) (*github.Repository, error)
  • func (s *Service) ProcessGithubEvent(ctx context.Context, rawEvent any) error
  • func (s *Service) ProcessUserGithubInstallation(ctx context.Context, userID string, installationID int64) error
  • func (s *Service) RevokeAuthToken(ctx context.Context, token string) error
  • func (s *Service) TeardownProject(ctx context.Context, p *database.Project) error
  • func (s *Service) TriggerReconcile(ctx context.Context, deploymentID string) error
  • func (s *Service) UpdateProject(ctx context.Context, p *database.Project) (*database.Project, error)
  • func (s *Service) ValidateAuthToken(ctx context.Context, token string) (AuthToken, error)

Constants

const AuthCodeTTL = 10 * time.Minute

Types

type AuthToken

type AuthToken interface {
	Token() *authtoken.Token
	OwnerID() string
}

AuthToken is the interface package admin uses to provide a consolidated view of a token string and its DB model.

type Options

type Options struct {
	DatabaseDriver      string
	DatabaseDSN         string
	GithubAppID         int64
	GithubAppPrivateKey string
	ProvisionerSpec     string
}

type Service

type Service struct {
	DB database.DB
	// contains filtered or unexported fields
}

func New

func New(opts *Options, logger *zap.Logger, issuer *auth.Issuer) (*Service, error)

func (*Service) Close

func (s *Service) Close() error

func (*Service) CreateOrUpdateUser

func (s *Service) CreateOrUpdateUser(ctx context.Context, email, name, photoURL string) (*database.User, error)

func (*Service) CreateProject

func (s *Service) CreateProject(ctx context.Context, proj *database.Project) (*database.Project, error)

func (*Service) GetUserGithubInstallation

func (s *Service) GetUserGithubInstallation(ctx context.Context, userID, githubURL string) (int64, bool, error)

GetUserGithubInstallation returns a Github installation ID iff the Github App is installed on the repository AND we have a confirmed relationship between the user and that installation. The githubURL should be a HTTPS URL for a Github repository without the .git suffix.

func (*Service) IssueAuthCode

func (s *Service) IssueAuthCode(ctx context.Context, clientID string) (*database.AuthCode, error)

func (*Service) IssueUserAuthToken

func (s *Service) IssueUserAuthToken(ctx context.Context, userID, clientID, displayName string) (AuthToken, error)

IssueUserAuthToken generates and persists a new auth token for a user.

func (*Service) LookupGithubRepo

func (s *Service) LookupGithubRepo(ctx context.Context, installationID int64, githubURL string) (*github.Repository, error)

LookupGithubRepo calls the Github API using an installation token to get information about a Github repo. The githubURL should be a HTTPS URL for a Github repository without the .git suffix.

func (*Service) ProcessGithubEvent

func (s *Service) ProcessGithubEvent(ctx context.Context, rawEvent any) error

ProcessGithubEvent processes a Github event (usually received over webhooks). After validating that the event is a valid Github event, it moves further processing to the background and returns a nil error.

func (*Service) ProcessUserGithubInstallation

func (s *Service) ProcessUserGithubInstallation(ctx context.Context, userID string, installationID int64) error

ProcessGithubInstallation tracks a confirmed relationship between a user and an installation of the Github App.

func (*Service) RevokeAuthToken

func (s *Service) RevokeAuthToken(ctx context.Context, token string) error

RevokeAuthToken removes an auth token from persistent storage.

func (*Service) TeardownProject

func (s *Service) TeardownProject(ctx context.Context, p *database.Project) error

func (*Service) TriggerReconcile

func (s *Service) TriggerReconcile(ctx context.Context, deploymentID string) error

func (*Service) UpdateProject

func (s *Service) UpdateProject(ctx context.Context, p *database.Project) (*database.Project, error)

func (*Service) ValidateAuthToken

func (s *Service) ValidateAuthToken(ctx context.Context, token string) (AuthToken, error)

ValidateAuthToken validates an auth token against persistent storage.