• Stars
    star
    527
  • Rank 84,091 (Top 2 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created almost 8 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Reference implementation of an apiserver for a custom Kubernetes API.

sample-apiserver

Demonstration of how to use the k8s.io/apiserver library to build a functional API server.

Note: go-get or vendor this package as k8s.io/sample-apiserver.

Purpose

You may use this code if you want to build an Extension API Server to use with API Aggregation, or to build a stand-alone Kubernetes-style API server.

However, consider two other options:

  • CRDs: if you just want to add a resource to your kubernetes cluster, then consider using Custom Resource Definition a.k.a CRDs. They require less coding and rebasing. Read about the differences between Custom Resource Definitions vs Extension API Servers here.
  • Apiserver-builder: If you want to build an Extension API server, consider using apiserver-builder instead of this repo. The Apiserver-builder is a complete framework for generating the apiserver, client libraries, and the installation program.

If you do decide to use this repository, then the recommended pattern is to fork this repository, modify it to add your types, and then periodically rebase your changes on top of this repo, to pick up improvements and bug fixes to the apiserver.

Compatibility

HEAD of this repo will match HEAD of k8s.io/apiserver, k8s.io/apimachinery, and k8s.io/client-go.

Where does it come from?

sample-apiserver is synced from https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/sample-apiserver. Code changes are made in that location, merged into k8s.io/kubernetes and later synced here.

Fetch sample-apiserver and its dependencies

Like the rest of Kubernetes, sample-apiserver has used godep and $GOPATH for years and is now adopting go 1.11 modules. There are thus two alternative ways to go about fetching this demo and its dependencies.

Fetch with godep

When NOT using go 1.11 modules, you can use the following commands.

go get -d k8s.io/sample-apiserver
cd $GOPATH/src/k8s.io/sample-apiserver  # assuming your GOPATH has just one entry
godep restore

When using go 1.11 modules

When using go 1.11 modules (GO111MODULE=on), issue the following commands --- starting in whatever working directory you like.

git clone https://github.com/kubernetes/sample-apiserver.git
cd sample-apiserver

Note, however, that if you intend to generate code then you will also need the code-generator repo to exist in an old-style location. One easy way to do this is to use the command go mod vendor to create and populate the vendor directory.

A Note on kubernetes/kubernetes

If you are developing Kubernetes according to https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md then you already have a copy of this demo in kubernetes/staging/src/k8s.io/sample-apiserver and its dependencies --- including the code generator --- are in usable locations.

Normal Build and Deploy

Changes to the Types

If you change the API object type definitions in any of the pkg/apis/.../types.go files then you will need to update the files generated from the type definitions. To do this, first create the vendor directory if necessary and then invoke hack/update-codegen.sh with sample-apiserver as your current working directory; the script takes no arguments.

Authentication plugins

The normal build supports only a very spare selection of authentication methods. There is a much larger set available in https://github.com/kubernetes/client-go/tree/master/plugin/pkg/client/auth . If you want your server to support one of those, such as oidc, then add an import of the appropriate package to sample-apiserver/main.go. Here is an example:

import _ "k8s.io/client-go/plugin/pkg/client/auth/oidc"

Alternatively you could add support for all of them, with an import like this:

import _ "k8s.io/client-go/plugin/pkg/client/auth"

Build the Binary

With sample-apiserver as your current working directory, issue the following command:

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -o artifacts/simple-image/kube-sample-apiserver

Build the Container Image

With sample-apiserver as your current working directory, issue the following commands with MYPREFIX and MYTAG replaced by something suitable.

docker build -t MYPREFIX/kube-sample-apiserver:MYTAG ./artifacts/simple-image
docker push MYPREFIX/kube-sample-apiserver:MYTAG

Deploy into a Kubernetes Cluster

Edit artifacts/example/deployment.yaml, updating the pod template's image reference to match what you pushed and setting the imagePullPolicy to something suitable. Then call:

kubectl apply -f artifacts/example

Running it stand-alone

During development it is helpful to run sample-apiserver stand-alone, i.e. without a Kubernetes API server for authn/authz and without aggregation. This is possible, but needs a couple of flags, keys and certs as described below. You will still need some kubeconfig, e.g. ~/.kube/config, but the Kubernetes cluster is not used for authn/z. A minikube or hack/local-up-cluster.sh cluster will work.

Instead of trusting the aggregator inside kube-apiserver, the described setup uses local client certificate based X.509 authentication and authorization. This means that the client certificate is trusted by a CA and the passed certificate contains the group membership to the system:masters group. As we disable delegated authorization with --authorization-skip-lookup, only this superuser group is authorized.

  1. First we need a CA to later sign the client certificate:

    openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
  2. Then we create a client cert signed by this CA for the user development in the superuser group system:masters:

    openssl req -out client.csr -new -newkey rsa:4096 -nodes -keyout client.key -subj "/CN=development/O=system:masters"
    openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 01 -sha256 -out client.crt
  3. As curl requires client certificates in p12 format with password, do the conversion:

    openssl pkcs12 -export -in ./client.crt -inkey ./client.key -out client.p12 -passout pass:password
  4. With these keys and certs in-place, we start the server:

    etcd &
    sample-apiserver --secure-port 8443 --etcd-servers http://127.0.0.1:2379 --v=7 \
       --client-ca-file ca.crt \
       --kubeconfig ~/.kube/config \
       --authentication-kubeconfig ~/.kube/config \
       --authorization-kubeconfig ~/.kube/config

    The first kubeconfig is used for the shared informers to access Kubernetes resources. The second kubeconfig passed to --authentication-kubeconfig is used to satisfy the delegated authenticator. The third kubeconfig passed to --authorized-kubeconfig is used to satisfy the delegated authorizer. Neither the authenticator, nor the authorizer will actually be used: due to --client-ca-file, our development X.509 certificate is accepted and authenticates us as system:masters member. system:masters is the superuser group such that delegated authorization is skipped.

  5. Use curl to access the server using the client certificate in p12 format for authentication:

    curl -fv -k --cert-type P12 --cert client.p12:password \
       https://localhost:8443/apis/wardle.example.com/v1alpha1/namespaces/default/flunders

    Or use wget:

    wget -O- --no-check-certificate \
       --certificate client.crt --private-key client.key \
       https://localhost:8443/apis/wardle.example.com/v1alpha1/namespaces/default/flunders

    Note: Recent OSX versions broke client certs with curl. On Mac try brew install httpie and then:

    http --verify=no --cert client.crt --cert-key client.key \
       https://localhost:8443/apis/wardle.example.com/v1alpha1/namespaces/default/flunders

More Repositories

1

kubernetes

Production-Grade Container Scheduling and Management
Go
109,583
star
2

minikube

Run Kubernetes locally
Go
29,215
star
3

ingress-nginx

Ingress-NGINX Controller for Kubernetes
Go
17,204
star
4

kops

Kubernetes Operations (kOps) - Production Grade k8s Installation, Upgrades and Management
Go
15,806
star
5

dashboard

General-purpose web UI for Kubernetes clusters
Go
14,250
star
6

community

Kubernetes community content
Jupyter Notebook
11,899
star
7

kompose

Convert Compose to Kubernetes
Go
9,453
star
8

client-go

Go client for Kubernetes.
Go
8,908
star
9

autoscaler

Autoscaling components for Kubernetes
Go
8,043
star
10

examples

Kubernetes application example tutorials
Shell
6,148
star
11

kube-state-metrics

Add-on agent to generate and expose cluster-level metrics.
Go
5,313
star
12

website

Kubernetes website and documentation repo:
HTML
4,437
star
13

test-infra

Test infrastructure for the Kubernetes project.
Go
3,817
star
14

kubeadm

Aggregator for issues filed against kubeadm
Go
3,728
star
15

enhancements

Enhancements tracking repo for Kubernetes
Go
3,380
star
16

sample-controller

Repository for sample controller. Complements sample-apiserver
Go
3,129
star
17

node-problem-detector

This is a place for various problem detectors running on the Kubernetes nodes.
Go
2,892
star
18

kubectl

Issue tracker and mirror of kubectl code
Go
2,811
star
19

git-sync

A sidecar app which clones a git repo and keeps it in sync with the upstream.
Shell
2,209
star
20

code-generator

Generators for kube-like API types
Go
1,692
star
21

ingress-gce

Ingress controller for Google Cloud
Go
1,269
star
22

dns

Kubernetes DNS service
Go
911
star
23

perf-tests

Performance tests and benchmarks
Go
883
star
24

apimachinery

Go
817
star
25

k8s.io

Code and configuration to manage Kubernetes project infrastructure, including various *.k8s.io sites
HCL
701
star
26

api

The canonical location of the Kubernetes API definition.
Go
647
star
27

apiserver

Library for writing a Kubernetes-style API server.
Go
644
star
28

cloud-provider-openstack

Go
612
star
29

gengo

gengo library for code generation.
Go
548
star
30

sig-release

Repo for SIG release
Shell
534
star
31

metrics

Kubernetes metrics-related API types and clients
Go
489
star
32

release

Release infrastructure for Kubernetes and related components
Go
484
star
33

design-proposals-archive

Archive of Kubernetes Design Proposals
Makefile
478
star
34

registry.k8s.io

This project is the repo for registry.k8s.io, the production OCI registry service for Kubernetes' container image artifacts
Go
385
star
35

cloud-provider-aws

Cloud provider for AWS
Go
382
star
36

cri-api

Container Runtime Interface (CRI) – a plugin interface which enables kubelet to use a wide variety of container runtimes.
Go
376
star
37

cloud-provider-alibaba-cloud

CloudProvider for Alibaba Cloud
Go
358
star
38

utils

Non-Kubernetes-specific utility libraries which are consumed by multiple projects.
Go
326
star
39

kube-openapi

Kubernetes OpenAPI spec generation & serving
Go
315
star
40

kubelet

kubelet component configs
Go
307
star
41

sample-cli-plugin

Sample kubectl plugin
Go
285
star
42

cli-runtime

Set of helpers for creating kubectl commands and plugins.
Go
282
star
43

kube-aggregator

Aggregator for Kubernetes-style API servers: dynamic registration, discovery summarization, secure proxy
Go
249
star
44

cloud-provider

cloud-provider defines the shared interfaces which Kubernetes cloud providers implement. These interfaces allow various controllers to integrate with any cloud provider in a pluggable fashion. Also serves as an issue tracker for SIG Cloud Provider.
Go
243
star
45

org

Meta configuration for Kubernetes Github Org
Go
242
star
46

cloud-provider-vsphere

Kubernetes Cloud Provider for vSphere https://cloud-provider-vsphere.sigs.k8s.io
Go
238
star
47

apiextensions-apiserver

API server for API extensions like CustomResourceDefinitions
Go
231
star
48

kubernetes-template-project

A template for starting new projects on the github.com/kubernetes organization
188
star
49

kube-proxy

kube-proxy component configs
Go
178
star
50

sig-security

Process documentation, non-code deliverables, and miscellaneous artifacts of Kubernetes SIG Security
Python
166
star
51

committee-security-response

Kubernetes Security Process and Security Committee docs
Python
163
star
52

kube-scheduler

kube-scheduler component configs
Go
162
star
53

cloud-provider-gcp

cloud-provider-gcp contains several projects used to run Kubernetes in Google Cloud
Go
115
star
54

component-base

Shared code for kubernetes core components
Go
106
star
55

repo-infra

Kubernetes repository infrastucture tools
Starlark
97
star
56

pod-security-admission

Kubernetes Pod Security Standards implementation - https://github.com/kubernetes/enhancements/blob/master/keps/sig-auth/2579-psp-replacement/README.md
Go
97
star
57

kube-controller-manager

kube-controller-manager component configs
Go
88
star
58

steering

The Kubernetes Steering Committee
83
star
59

publishing-bot

Code behind the robot to publish from staging to real repositories.
Go
82
star
60

controller-manager

This repo is intended to contain common public library code for kube-controller-manager, cloud-controller-manager as well as any other controller managers which people build.
Go
68
star
61

contributor-site

Code for kubernetes.dev
HTML
66
star
62

mount-utils

Package mount defines an interface to mounting filesystems.
Go
56
star
63

legacy-cloud-providers

This repository hosts the legacy in-tree cloud providers. Out-of-tree cloud providers can consume packages in this repo to support legacy implementations of their Kubernetes cloud provider.
Go
51
star
64

system-validators

A set of system-oriented validators for kubeadm preflight checks.
Go
34
star
65

cluster-bootstrap

Go
31
star
66

dynamic-resource-allocation

Go
23
star
67

cloud-provider-sample

Sample of how to build a cloud provider repo. This will build a Kubernetes image which deploys on bare metal. It uses the fake cloud provider. It consumes the K8s/K8s build artifact and adds to it the Cloud Controller Manager and CSI Daemon Set.
21
star
68

kms

Kubernetes KMS implementation
Go
18
star
69

node-api

Go
14
star
70

component-helpers

High-level helpers for Kubernetes components
Go
13
star
71

csi-translation-lib

Staging repo for CSI Migration/Translation libraries
Go
12
star
72

cel-admission-webhook

Go
11
star
73

endpointslice

Go
6
star
74

sig-testing

Home for SIG Testing discussion and documents.
6
star
75

cri-client

Container Runtime Interface client implementation
Go
3
star
76

.github

Default files for all repos in the Kubernetes GitHub org
1
star