Skip to content

Commit fa0fe69

Browse files
adoheadohe
committed
feat: add KubernetesMetadata extensions and reorg schema directory
1 parent c56fa27 commit fa0fe69

File tree

18 files changed

+423
-374
lines changed

18 files changed

+423
-374
lines changed

‎core/v1/accessory.k‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
schema Accessory(Object):
2+
""" Accessory refers to various runtime capabilities and operational requirements provided by the underlying
3+
infrastructure, such as database, gateway, cache e.g. All specific accessory schema definitions must inherit
4+
the Accessory schema.
5+
"""

v1/app_configuration.k renamed to core/v1/app_configuration.k

Lines changed: 11 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,30 @@
1-
import v1.workload as wl
1+
import extensions.v1 as extv1
22

3-
schema AppConfiguration:
3+
schema AppConfiguration(Object):
44
""" AppConfiguration is a developer-centric definition that describes how to run an Application.
55
This application model builds upon a decade of experience at AntGroup running super large scale
66
internal developer platform, combined with best-of-breed ideas and practices from the community.
77
88
Attributes
99
----------
10-
workload: wl.Service | wl.Job, default is Undefined, required.
10+
workload: Service | Job, default is Undefined, required.
1111
Workload defines how to run your application code. Currently supported workload profile
1212
includes Service and Job.
1313
accessories: {str:any}, default is Undefined, optional.
1414
Accessories defines a collection of accessories that will be attached to the workload.
15-
labels: {str:str}, default is Undefined, optional.
15+
extensions: [extv1.KubernetesMetadata], default is Undefined, optional.
1616
Labels can be used to attach arbitrary metadata as key-value pairs to resources.
17-
annotations: {str:str}, default is Undefined, optional.
18-
Annotations are key/value pairs that attach arbitrary non-identifying metadata to resources.
1917
2018
Examples
2119
--------
2220
# Instantiate an App with a long-running service and its image is "nginx:v1"
2321
24-
import kam as ac
25-
import kam.workload as wl
26-
import kam.workload.container as c
22+
import kam.core.v1 as v1
2723
28-
helloworld : ac.AppConfiguration {
29-
workload: wl.Service {
24+
helloworld : v1.AppConfiguration {
25+
workload: v1.Service {
3026
containers: {
31-
"nginx": c.Container {
27+
"nginx": v1.Container {
3228
image: "nginx:v1"
3329
}
3430
}
@@ -37,12 +33,10 @@ schema AppConfiguration:
3733
"""
3834

3935
# Workload defines how to run your application code.
40-
workload: wl.Service | wl.Job
36+
workload: Workload
4137

4238
# Accessories defines a collection of accessories that will be attached to the workload.
43-
accessories?: {str:any}
39+
accessories?: {str:Accessory}
4440

45-
###### Other metadata info
4641
# Labels and annotations can be used to attach arbitrary metadata as key-value pairs to resources.
47-
labels?: {str:str}
48-
annotations?: {str:str}
42+
extensions?: [extv1.KubernetesMetadata]

‎core/v1/container.k‎

Lines changed: 318 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,318 @@
1+
import regex
2+
3+
schema Container:
4+
""" Container describes how the Application's tasks are expected to be run. Depending on
5+
the replicas parameter 1 or more containers can be created from each template.
6+
7+
Attributes
8+
----------
9+
image: str, default is Undefined, required.
10+
Image refers to the Docker image name to run for this container.
11+
More info: https://kubernetes.io/docs/concepts/containers/images
12+
command: [str], default is Undefined, optional.
13+
Entrypoint array. Not executed within a shell.
14+
Command will overwrite the ENTRYPOINT value set in the Dockfile, otherwise the Docker
15+
image's ENTRYPOINT is used if this is not provided.
16+
args: [str], default is Undefined, optional.
17+
Arguments to the entrypoint.
18+
Args will overwrite the CMD value set in the Dockfile, otherwise the Docker
19+
image's CMD is used if this is not provided.
20+
env: {str:str}, default is Undefined, optional.
21+
List of environment variables to set in the container.
22+
The value of the environment variable may be static text or a value from a secret.
23+
workingDir: str, default is Undefined, optional.
24+
The working directory of the running process defined in entrypoint.
25+
Default container runtime will be used if this is not specified.
26+
resources: {str:str}, default is Undefined, optional.
27+
Map of resource requirements the container should run with.
28+
The resources parameter is a dict with the key being the resource name and the value being
29+
the resource value.
30+
files: {str:FileSpec}, default is Undefined, optional.
31+
List of files to create in the container.
32+
The files parameter is a dict with the key being the file name in the container and the value
33+
being the target file specification.
34+
dirs: {str:str}, default is Undefined, optional.
35+
Collection of volumes mount into the container's filesystem.
36+
The dirs parameter is a dict with the key being the folder name in the container and the value
37+
being the referenced volume.
38+
livenessProbe: Probe, default is Undefined, optional.
39+
LivenessProbe indicates if a running process is healthy.
40+
Container will be restarted if the probe fails.
41+
readinessProbe: Probe, default is Undefined, optional.
42+
ReadinessProbe indicates whether an application is available to handle requests.
43+
startupProbe: Probe, default is Undefined, optional.
44+
StartupProbe indicates that the container has started for the first time.
45+
Container will be restarted if the probe fails.
46+
lifecycle: Lifecycle, default is Undefined, optional.
47+
Lifecycle refers to actions that the management system should take in response to container lifecycle events.
48+
49+
Examples
50+
--------
51+
import kam.core.v1 as v1
52+
53+
web = v1.Container {
54+
image: "nginx:latest"
55+
command: ["/bin/sh", "-c", "echo hi"]
56+
env: {
57+
"name": "value"
58+
}
59+
resources: {
60+
"cpu": "2"
61+
"memory": "4Gi"
62+
}
63+
}
64+
"""
65+
66+
# Image to run for this container.
67+
image: str
68+
69+
# Entrypoint array.
70+
# The image's ENTRYPOINT is used if this is not provided.
71+
command?: [str]
72+
# Arguments to the entrypoint.
73+
# The image's CMD is used if this is not provided.
74+
args?: [str]
75+
# Collection of environment variables to set in the container.
76+
# The value of environment variable may be static text or a value from a secret.
77+
env?: {str:str}
78+
# The current working directory of the running process defined in entrypoint.
79+
workingDir?: str
80+
81+
# Resource requirements for this container.
82+
resources?: {str:str}
83+
84+
# Files configures one or more files to be created in the container.
85+
files?: {str:FileSpec}
86+
# Dirs configures one or more volumes to be mounted to the specified folder.
87+
dirs?: {str:str}
88+
89+
# Liveness probe for this container.
90+
# Liveness probe indicates if a running process is healthy.
91+
livenessProbe?: Probe
92+
# Readiness probe for this container.
93+
# Readiness probe indicates whether an application is available to handle requests.
94+
readinessProbe?: Probe
95+
# Startup probe for this container.
96+
# Startup probe indicates that the container has started for the first time.
97+
startupProbe?: Probe
98+
99+
# Lifecycle configures actions which should be taken response to container lifecycle
100+
# events.
101+
lifecycle?: Lifecycle
102+
103+
check:
104+
all e in env {
105+
regex.match(e, r"^[-._a-zA-Z][-._a-zA-Z0-9]*$")
106+
} if env, "a valid environment variable name must consist of alphabetic characters, digits, '_', '-', or '.', and must not start with a digit"
107+
108+
schema FileSpec:
109+
""" FileSpec defines the target file in a Container.
110+
111+
Attributes
112+
----------
113+
content: str, default is Undefined, optional.
114+
File content in plain text.
115+
contentFrom: str, default is Undefined, optional.
116+
Source for the file content, reference to a secret of configmap value.
117+
mode: str, default is Undefined, optional.
118+
Mode bits used to set permissions on this file, must be an octal value
119+
between 0000 and 0777 or a decimal value between 0 and 511
120+
121+
Examples
122+
--------
123+
import kam.core.v1 as v1
124+
125+
tmpFile = v1.FileSpec {
126+
content: "some file contents"
127+
mode: "0777"
128+
}
129+
"""
130+
131+
# The content of target file in plain text.
132+
content?: str
133+
134+
# Source for the file content, might be a reference to a secret value.
135+
contentFrom?: str
136+
137+
# Mode bits used to set permissions on this file.
138+
# Defaults to 0644.
139+
mode: str = "0644"
140+
141+
check:
142+
not content or not contentFrom, "content and contentFrom are mutually exclusive"
143+
regex.match(mode, r"^[0-7]{3,4}$"), "valid mode must between 0000 and 0777, both inclusive"
144+
145+
schema Probe:
146+
""" Probe describes a health check to be performed against a container to determine whether it is
147+
alive or ready to receive traffic. There are three probe types: readiness, liveness, and startup.
148+
149+
Attributes
150+
----------
151+
probeHandler: Exec | Http | Tcp, default is Undefined, required.
152+
The action taken to determine the alive or health of a container
153+
initialDelaySeconds: int, default is Undefined, optional.
154+
The number of seconds before health checking is activated.
155+
More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
156+
timeoutSeconds: int, default is Undefined, optional.
157+
The number of seconds after which the probe times out.
158+
More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
159+
periodSeconds: int, default is Undefined, optional.
160+
How often (in seconds) to perform the probe.
161+
successThreshold: int, default is Undefined, optional.
162+
Minimum consecutive successes for the probe to be considered successful after having failed.
163+
failureThreshold: int, default is Undefined, optional.
164+
Minimum consecutive failures for the probe to be considered failed after having succeeded.
165+
terminationGracePeriod: int, default is Undefined, optional.
166+
Duration in seconds before terminate gracefully upon probe failure.
167+
168+
Examples
169+
--------
170+
import kam.core.v1 as v1
171+
172+
probe = v1.Probe {
173+
probeHandler: v1.Http {
174+
path: "/healthz"
175+
}
176+
initialDelaySeconds: 10
177+
}
178+
"""
179+
180+
# The action taken to determine the health of a container
181+
probeHandler: Exec | Http | Tcp
182+
183+
# Number of seconds after the container has started before liveness probes are initiated.
184+
initialDelaySeconds?: int
185+
186+
# Number of seconds after which the probe times out.
187+
timeoutSeconds?: int
188+
189+
# How often (in seconds) to perform the probe.
190+
periodSeconds?: int
191+
192+
# Minimum consecutive successes for the probe to be considered successful after having failed.
193+
successThreshold?: int
194+
195+
# Minimum consecutive failures for the probe to be considered failed after having succeeded.
196+
failureThreshold?: int
197+
198+
# Duration in seconds before terminate gracefully upon probe failure.
199+
terminationGracePeriod?: int
200+
201+
check:
202+
initialDelaySeconds >= 0 if initialDelaySeconds, "initialDelaySeconds must be greater than or equal to 0"
203+
timeoutSeconds >= 0 if timeoutSeconds, "timeoutSeconds must be greater than or equal to 0"
204+
periodSeconds >= 0 if periodSeconds, "periodSeconds must be greater than or equal to 0"
205+
successThreshold >= 0 if successThreshold, "successThreshold must be greater than or equal to 0"
206+
failureThreshold >= 0 if failureThreshold, "failureThreshold must be greater than or equal to 0"
207+
terminationGracePeriod >= 0 if terminationGracePeriod, "terminationGracePeriod must be greater than or equal to 0"
208+
209+
schema Exec:
210+
""" Exec describes a "run in container" action.
211+
212+
Attributes
213+
----------
214+
command: [str], default is Undefined, required.
215+
The command line to execute inside the container.
216+
217+
Examples
218+
--------
219+
import kam.core.v1 as v1
220+
221+
execProbe = v1.Exec {
222+
command: ["probe.sh"]
223+
}
224+
"""
225+
226+
# The command line to execute inside the container.
227+
# Exit status of 0 is treated as live/healthy and non-zero is unhealthy.
228+
command: [str]
229+
230+
check:
231+
len(command) > 0, "command must be specified"
232+
233+
schema Http:
234+
""" Http describes an action based on HTTP Get requests.
235+
236+
Attributes
237+
----------
238+
url: str, default is Undefined, required.
239+
The full qualified url to send HTTP requests.
240+
headers: {str:str}, default is Undefined, optional.
241+
Collection of custom headers to set in the request
242+
243+
Examples
244+
--------
245+
import kam.core.v1 as v1
246+
247+
httpProbe = v1.Http {
248+
url: "http://localhost:80"
249+
headers: {
250+
"X-HEADER": "VALUE"
251+
}
252+
}
253+
"""
254+
255+
# The full qualified url to send HTTP requests.
256+
url: str
257+
258+
# Custom headers to set in the request.
259+
headers?: {str:str}
260+
261+
check:
262+
all header in headers {
263+
regex.match(header, r"^[-A-Za-z0-9]+$")
264+
} if headers, "a valid HTTP header must consist of alphanumeric characters or '-' e.g X-Header-Name"
265+
266+
schema Tcp:
267+
""" Tcp describes an action based on opening a socket.
268+
269+
Attributes
270+
----------
271+
url: str, default is Undefined, required.
272+
The full qualified url to open a socket.
273+
274+
Examples
275+
--------
276+
import kam.core.v1 as v1
277+
278+
tcpProbe = v1.Tcp {
279+
url: "tcp://localhost:1234"
280+
}
281+
"""
282+
283+
# The full qualified url to open a socket.
284+
url: str
285+
286+
schema Lifecycle:
287+
""" Lifecycle describes actions that the management system should take in response
288+
to container lifecycle events.
289+
290+
Attributes
291+
----------
292+
preStop: p.Exec | p.Http, default is Undefined, optional.
293+
The action to be taken before a container is terminated due to an API request or
294+
management event such as liveness/startup probe failure, preemption, resource contention, etc.
295+
More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks
296+
postStart: p.Exec | p.Http, default is Undefined, optional.
297+
The action to be taken after a container is created.
298+
More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks
299+
300+
Examples
301+
--------
302+
import kam.core.v1 as v1
303+
304+
lifecycleHook = v1.Lifecycle {
305+
preStop: v1.Exec {
306+
command: ["preStop.sh"]
307+
}
308+
postStart: v1.Http {
309+
url: "http://localhost:80"
310+
}
311+
}
312+
"""
313+
314+
# The action to be taken before a container is terminated.
315+
preStop?: Exec | Http
316+
317+
# The action to be taken after a container is created.
318+
postStart?: Exec | Http

‎core/v1/exclusive_accessory.k‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
schema ExclusiveAccessory(Accessory):
2+
""" For specific accessory schema definition, if there should be only one instance within AppConfiguration, must
3+
inherit the ExclusiveAccessory schema.
4+
"""
5+

0 commit comments

Comments
 (0)