server

README

Unikorn Server

Code Generation

Everything is done with an OpenAPI schema. This allows us to auto-generate the server routing, schema validation middleware, types and clients. This happens automatically on update via the Makefile. Please ensure updated generated code is commited with your pull request.

API Definition

Consult the OpenAPI schema for full details of what it does.

Getting Started with Development and Testing.

Once everything is up and running, grab the IP address:

export INGRESS_ADDR=$(kubectl -n unikorn get ingress/unikorn-server -o 'jsonpath={.status.loadBalancer.ingress[0].ip}')

And add it to your resolver:

echo "${INGRESS_ADDR} kubernetes.eschercloud.com" >> /etc/hosts

API Testing

This does what a client is expected to do to bootstrap a session. Copy this, make a script, whatever works for you!

Get an Unscoped Token

When you first log in the the system you'll supply a username and password:

export TOKEN=$(curl -vkq https://kubernetes.eschercloud.com/api/v1/auth/tokens/password -X POST -u 'username:password' | jq  -r .token)

Get a List of Projects

The token from the previous step allows very little functionality e.g. you cannot see any images or flavors. We need a scoped token for that:

curl -vkq https://kubernetes.eschercloud.com/api/v1/providers/openstack/projects -H "Authorization: Bearer ${TOKEN}" | jq  .

It is anticipated that this step can be omitted most of the time for a Web application, as the project preference can be cached in window.localStorage to persist across sessions.

Get a Scoped Token

Grab a token that is scoped to a specific project and you can begin hitting other APIs:

export TOKEN=$(curl -vkq https://kubernetes.eschercloud.com/api/v1/auth/tokens/token -H "Authorization: Bearer ${TOKEN}" -d '{"project":{"id":"23a9e437091d481da99f2aa07180b4ea"}}' | jq  -r token)

Documentation

Index

• type Options
  • func (o *Options) AddFlags(f *pflag.FlagSet)
• type Server
  • func (s *Server) AddFlags(goflags *flag.FlagSet, flags *pflag.FlagSet)
  • func (s *Server) GetServer(client client.Client) (*http.Server, error)
  • func (s *Server) SetupLogging()
  • func (s *Server) SetupOpenTelemetry(ctx context.Context) error

Types

type Options

type Options struct {
	Namespace string

	// ListenAddress tells the server what to listen on, you shouldn't
	// need to change this, its already non-privileged and the default
	// should be modified to avoid clashes with other services e.g prometheus.
	ListenAddress string

	// ReadTimeout defines how long before we give up on the client,
	// this should be fairly short.
	ReadTimeout time.Duration

	// ReadHeaderTimeout defines how long before we give up on the client,
	// this should be fairly short.
	ReadHeaderTimeout time.Duration

	// WriteTimeout defines how long we take to respond before we give up.
	// Ideally we'd like this to be short, but Openstack in general sucks
	// for performance.  Additionally some calls like cluster creation can
	// do a cascading create, e.g. create a default control plane, than in
	// turn creates a project.
	WriteTimeout time.Duration

	// OTLPEndpoint defines whether to ship spans to an OTLP consumer or
	// not, and where to send them to.
	OTLPEndpoint string

	// RequestTimeout places a hard limit on all requests lengths.
	RequestTimeout time.Duration
}

Options allows server options to be overridden.

func (*Options) AddFlags

func (o *Options) AddFlags(f *pflag.FlagSet)

addFlags allows server options to be modified.

type Server

type Server struct {
	// Options are server specific options e.g. listener address etc.
	Options Options

	// ZapOptions configure logging.
	ZapOptions zap.Options

	// HandlerOptions sets options for the HTTP handler.
	HandlerOptions handler.Options

	// JoseOptions sets options for JWE.
	JoseOptions jose.Options

	// OAuth2Options sets options for the oauth2/oidc authenticator.
	OAuth2Options oauth2.Options

	// CORSOptions are for remote resource sharing.
	CORSOptions cors.Options
}

func (*Server) AddFlags

func (s *Server) AddFlags(goflags *flag.FlagSet, flags *pflag.FlagSet)

func (*Server) GetServer

func (s *Server) GetServer(client client.Client) (*http.Server, error)

func (*Server) SetupLogging

func (s *Server) SetupLogging()

func (*Server) SetupOpenTelemetry

func (s *Server) SetupOpenTelemetry(ctx context.Context) error

SetupOpenTelemetry adds a span processor that will print root spans to the logs by default, and optionally ship the spans to an OTLP listener. TODO: move config into an otel specific options struct.