Skip to content

Commit 7c159be

Browse files
zshihangzshihang
committed
port serviceaccount token volume design proposal to KEP
on top of this, i'll add the proposal for file permission handling
1 parent ffcab6d commit 7c159be

File tree

1 file changed

+179
-0
lines changed

1 file changed

+179
-0
lines changed

‎keps/sig-storage/20180515-svcacct-token-volumes.md

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
title: Service Account Token Volumes
3+
authors:
4+
- "@smarterclayton"
5+
- "@liggitt"
6+
- "@mikedanese"
7+
owning-sig: sig-storage
8+
participating-sigs:
9+
- sig-auth
10+
reviewers:
11+
- "@jsafrane"
12+
- "@tallclair"
13+
approvers:
14+
- "@saad-ali"
15+
editor: "@zshihang"
16+
creation-date: 2018-05-15
17+
last-updated: 2020-03-09
18+
status: implemented
19+
see-also:
20+
- "https://github.com/kubernetes/community/blob/e3a6b8172fec9506b15520549e52be683e30cbfb/contributors/design-proposals/storage/svcacct-token-volume-source.md"
21+
---
22+
23+
# Service Account Token Volumes
24+
25+
## Table of Contents
26+
27+
<!-- toc -->
28+
- [Summary](#summary)
29+
- [Motivation](#motivation)
30+
- [Proposal](#proposal)
31+
- [Token Volume Projection](#token-volume-projection)
32+
- [Alternatives](#alternatives)
33+
- [Graduation Criteria](#graduation-criteria)
34+
<!-- /toc -->
35+
36+
## Summary
37+
38+
Kubernetes is able to provide pods with unique identity tokens that can prove
39+
the caller is a particular pod to a Kubernetes API server. These tokens are
40+
injected into pods as secrets. This proposal proposes a new mechanism of
41+
distribution with support for improved service account tokens and explores how
42+
to migrate from the existing mechanism backwards compatibly.
43+
44+
## Motivation
45+
46+
Many workloads running on Kubernetes need to prove to external parties who they
47+
are in order to participate in a larger application environment. This identity
48+
must be attested to by the orchestration system in a way that allows a third
49+
party to trust that an arbitrary container on the cluster is who it says it is.
50+
In addition, infrastructure running on top of Kubernetes needs a simple
51+
mechanism to communicate with the Kubernetes APIs and to provide more complex
52+
tooling. Finally, a significant set of security challenges are associated with
53+
storing service account tokens as secrets in Kubernetes and limiting the methods
54+
whereby malicious parties can get access to these tokens will reduce the risk of
55+
platform compromise.
56+
57+
As a platform, Kubernetes should evolve to allow identity management systems to
58+
provide more powerful workload identity without breaking existing use cases, and
59+
provide a simple out of the box workload identity that is sufficient to cover
60+
the requirements of bootstrapping low-level infrastructure running on
61+
Kubernetes. We expect that other systems to cover the more advanced scenarios,
62+
and see this effort as necessary glue to allow more powerful systems to succeed.
63+
64+
With this feature, we hope to provide a backwards compatible replacement for
65+
service account tokens that strengthens the security and improves the
66+
scalability of the platform.
67+
68+
69+
## Proposal
70+
71+
Kubernetes should implement a ServiceAccountToken volume projection that
72+
maintains a service account token requested by the node from the TokenRequest
73+
API.
74+
75+
### Token Volume Projection
76+
77+
A new volume projection will be implemented with an API that closely matches the
78+
TokenRequest API.
79+
80+
```go
81+
type ProjectedVolumeSource struct {
82+
Sources []VolumeProjection
83+
DefaultMode *int32
84+
}
85+
86+
type VolumeProjection struct {
87+
Secret *SecretProjection
88+
DownwardAPI *DownwardAPIProjection
89+
ConfigMap *ConfigMapProjection
90+
ServiceAccountToken *ServiceAccountTokenProjection
91+
}
92+
93+
// ServiceAccountTokenProjection represents a projected service account token
94+
// volume. This projection can be used to insert a service account token into
95+
// the pods runtime filesystem for use against APIs (Kubernetes API Server or
96+
// otherwise).
97+
type ServiceAccountTokenProjection struct {
98+
// Audience is the intended audience of the token. A recipient of a token
99+
// must identify itself with an identifier specified in the audience of the
100+
// token, and otherwise should reject the token. The audience defaults to the
101+
// identifier of the apiserver.
102+
Audience string
103+
// ExpirationSeconds is the requested duration of validity of the service
104+
// account token. As the token approaches expiration, the kubelet volume
105+
// plugin will proactively rotate the service account token. The kubelet will
106+
// start trying to rotate the token if the token is older than 80 percent of
107+
// its time to live or if the token is older than 24 hours.Defaults to 1 hour
108+
// and must be at least 10 minutes.
109+
ExpirationSeconds int64
110+
// Path is the relative path of the file to project the token into.
111+
Path string
112+
}
113+
```
114+
115+
A volume plugin implemented in the kubelet will project a service account token
116+
sourced from the TokenRequest API into volumes created from
117+
ProjectedVolumeSources. As the token approaches expiration, the kubelet volume
118+
plugin will proactively rotate the service account token. The kubelet will start
119+
trying to rotate the token if the token is older than 80 percent of its time to
120+
live or if the token is older than 24 hours.
121+
122+
To replace the current service account token secrets, we also need to inject the
123+
clusters CA certificate bundle. Initially we will deploy to data in a configmap
124+
per-namespace and reference it using a ConfigMapProjection.
125+
126+
A projected volume source that is equivalent to the current service account
127+
secret:
128+
129+
```yaml
130+
sources:
131+
- serviceAccountToken:
132+
expirationSeconds: 3153600000 # 100 years
133+
path: token
134+
- configMap:
135+
name: kube-cacrt
136+
items:
137+
- key: ca.crt
138+
path: ca.crt
139+
- downwardAPI:
140+
items:
141+
- path: namespace
142+
fieldRef: metadata.namespace
143+
```
144+
145+
146+
This fixes one scalability issue with the current service account token
147+
deployment model where secret GETs are a large portion of overall apiserver
148+
traffic.
149+
150+
A projected volume source that requests a token for vault and Istio CA:
151+
152+
```yaml
153+
sources:
154+
- serviceAccountToken:
155+
path: vault-token
156+
audience: vault
157+
- serviceAccountToken:
158+
path: istio-token
159+
audience: ca.istio.io
160+
```
161+
162+
### Alternatives
163+
164+
1. Instead of implementing a service account token volume projection, we could
165+
implement all injection as a flex volume or CSI plugin.
166+
1. Both flex volume and CSI are alpha and are unlikely to graduate soon.
167+
1. Virtual kubelets (like Fargate or ACS) may not be able to run flex
168+
volumes.
169+
1. Service account tokens are a fundamental part of our API.
170+
1. Remove service accounts and service account tokens completely from core, use
171+
an alternate mechanism that sits outside the platform.
172+
1. Other core features need service account integration, leading to all
173+
users needing to install this extension.
174+
1. Complicates installation for the majority of users.
175+
176+
177+
## Graduation Criteria
178+
179+
TBD

0 commit comments

Comments
 (0)