Phoenix Operator API reference
Preface
Generally, the Phoneix Operator is a so-called Kubernetes Operator, which is ableextend the Kubernetes API, and also use it as a backend database. Therefor any API communication is done via the Kubernetes API rather than directly to Phoenix.
Useful links:
- Kubernetes Operator pattern concept: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/
- Kubernetes API reference: https://kubernetes.io/docs/reference/
- Access Custom Resources in the Kubernetes API: https://kubernetes.io/docs/reference/kubernetes-api/extend-resources/custom-resource-definition-v1/
- Access the Kubernetes API: https://kubernetes.io/docs/tasks/administer-cluster/access-cluster-api/
Moving Target Defence object
In the following you can find the custom resource definition of the “movingtargetdefense” object, along with the OpenAPI3 schema definition of the fields and types:
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.4.1
name: movingtargetdefenses.phoenix.r6security.com
spec:
conversion:
strategy: None
group: phoenix.r6security.com
names:
kind: MovingTargetDefense
listKind: MovingTargetDefenseList
plural: movingtargetdefenses
singular: movingtargetdefense
scope: Namespaced
versions:
- name: v1alpha1
schema:
openAPIV3Schema:
description: MovingTargetDefense is the Schema for the
movingtargetdefenses
API
properties:
apiVersion:
description: 'APIVersion defines the versioned schema of
this representation
of an object. Servers should convert recognized
schemas to the latest
internal value, and may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-
architecture/api-conventions.md#resources'
type: string
kind:
description: 'Kind is a string value representing the
REST resource this
object represents. Servers may infer this from the
endpoint the client
submits requests to. Cannot be updated. In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-
architecture/api-conventions.md#types-kinds'
type: string
metadata:
type: object
spec:
description: MovingTargetDefenseSpec defines the desired
state of MovingTargetDefense
properties:
historyLenght:
description: Maximum size of terminated pods list
minimum: 0
type: integer
podSelector:
additionalProperties:
type: string
description: PodSelector is the selector of a
Kubernetes Pods on which
the user desires to enable moving target defense
type: object
strategy:
description: Define strategy to delete target pods
properties:
action:
description: Define how to move the target after
expired
enum:
- Delete
- Save
- Relabel
type: string
lifetimestrategy:
description: 'Define how to get the pods
lifetime. (can be a fix
time or a random generated) Constant: each pod
killed after
fix time SafeConstant: try to apply fix time,
but will wait
if other pod will be killed near that Random:
Kill pods after
random time between MinTime and MaxTime'
enum:
- Constant
- SafeConstant
- Random
- Cron
- Event
type: string
max:
description: Define maximum lifetime of a pod.
(sec) Use only
if `LifetimeSrategy` is `Random`
format: int32
minimum: 0
type: integer
min:
description: Define minimum lifetime of a pod.
(sec) Use only
if `LifetimeSrategy` is `Random`
format: int32
minimum: 0
type: integer
newLabels:
additionalProperties:
type: string
description: Specify new labels for pods if
Relabel actioan was
selected.
type: object
schedule:
description: 'Cron type schedule expression.
Examples: https://pkg.go.dev/github.com/robfig/cron#Parse
Use only if `LifetimeSrategy` is `Cron`'
type: string
time:
description: Define lifetime of a pod. (sec) Use
only if `LifetimeSrategy`
is `Constant` or `SafeConstant`
format: int32
minimum: 0
type: integer
required:
- action
- lifetimestrategy
type: object
required:
- podSelector
- strategy
type: object
status:
description: MovingTargetDefenseStatus defines the
observed state of MovingTargetDefense
properties:
killedPodCounter:
description: Number of killed pod (useful when
history limit is reached
and len(deletedPod) != actualy deleted pod
counter)
type: integer
podsTerminated:
description: PodsTerminated is a counter that
represents the number
of Pods that was terminated by the operator
items:
description: Structure to the watching pods
properties:
lifetime:
description: Time when pods need to kill
type: string
name:
description: name of the pod
type: string
relativeTimeToLive:
description: Relative kill time in seconds
type: string
required:
- lifetime
- name
type: object
type: array
podsToWatch:
description: PodNames are list of Pods controlled by
the MTD operator
items:
description: Structure to the watching pods
properties:
lifetime:
description: Time when pods need to kill
type: string
name:
description: name of the pod
type: string
relativeTimeToLive:
description: Relative kill time in seconds
type: string
required:
- lifetime
- name
type: object
type: array
required:
- killedPodCounter
- podsTerminated
- podsToWatch
type: object
type: object
served: true
storage: true
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.4.1
name: movingtargetdefenses.phoenix.r6security.com
spec:
conversion:
strategy: None
group: phoenix.r6security.com
names:
kind: MovingTargetDefense
listKind: MovingTargetDefenseList
plural: movingtargetdefenses
singular: movingtargetdefense
scope: Namespaced
versions:
- name: v1alpha1
schema:
openAPIV3Schema:
description: MovingTargetDefense is the Schema for the
movingtargetdefenses
API
properties:
apiVersion:
description: 'APIVersion defines the versioned schema of
this representation
of an object. Servers should convert recognized
schemas to the latest
internal value, and may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-
architecture/api-conventions.md#resources'
type: string
kind:
description: 'Kind is a string value representing the
REST resource this
object represents. Servers may infer this from the
endpoint the client
submits requests to. Cannot be updated. In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-
architecture/api-conventions.md#types-kinds'
type: string
metadata:
type: object
spec:
description: MovingTargetDefenseSpec defines the desired
state of MovingTargetDefense
properties:
historyLenght:
description: Maximum size of terminated pods list
minimum: 0
type: integer
podSelector:
additionalProperties:
type: string
description: PodSelector is the selector of a
Kubernetes Pods on which
the user desires to enable moving target defense
type: object
strategy:
description: Define strategy to delete target pods
properties:
action:
description: Define how to move the target after
expired
enum:
- Delete
- Save
- Relabel
type: string
lifetimestrategy:
description: 'Define how to get the pods
lifetime. (can be a fix
time or a random generated) Constant: each pod
killed after
fix time SafeConstant: try to apply fix time,
but will wait
if other pod will be killed near that Random:
Kill pods after
random time between MinTime and MaxTime'
enum:
- Constant
- SafeConstant
- Random
- Cron
- Event
type: string
max:
description: Define maximum lifetime of a pod.
(sec) Use only
if `LifetimeSrategy` is `Random`
format: int32
minimum: 0
type: integer
min:
description: Define minimum lifetime of a pod.
(sec) Use only
if `LifetimeSrategy` is `Random`
format: int32
minimum: 0
type: integer
newLabels:
additionalProperties:
type: string
description: Specify new labels for pods if
Relabel actioan was
selected.
type: object
schedule:
description: 'Cron type schedule expression.
Examples: https://pkg.go.dev/github.com/robfig/cron#Parse
Use only if `LifetimeSrategy` is `Cron`'
type: string
time:
description: Define lifetime of a pod. (sec) Use
only if `LifetimeSrategy`
is `Constant` or `SafeConstant`
format: int32
minimum: 0
type: integer
required:
- action
- lifetimestrategy
type: object
required:
- podSelector
- strategy
type: object
status:
description: MovingTargetDefenseStatus defines the
observed state of MovingTargetDefense
properties:
killedPodCounter:
description: Number of killed pod (useful when
history limit is reached
and len(deletedPod) != actualy deleted pod
counter)
type: integer
podsTerminated:
description: PodsTerminated is a counter that
represents the number
of Pods that was terminated by the operator
items:
description: Structure to the watching pods
properties:
lifetime:
description: Time when pods need to kill
type: string
name:
description: name of the pod
type: string
relativeTimeToLive:
description: Relative kill time in seconds
type: string
required:
- lifetime
- name
type: object
type: array
podsToWatch:
description: PodNames are list of Pods controlled by
the MTD operator
items:
description: Structure to the watching pods
properties:
lifetime:
description: Time when pods need to kill
type: string
name:
description: name of the pod
type: string
relativeTimeToLive:
description: Relative kill time in seconds
type: string
required:
- lifetime
- name
type: object
type: array
required:
- killedPodCounter
- podsTerminated
- podsToWatch
type: object
type: object
served: true
storage: true
Example for access an object
Accessing the standard Kubernetes API requires a service account that needs to be set before the connection, or for e.g. you can also use “kubectl proxy” if you
have kubectl set up. For the sake of simplicity, in this guide we will use the
“kubectl get –raw <api endpoint>”
for similar purpose.
You can query the existing moving target defence policies with the following command / API call:
kubectl get --raw /apis/phoenix.r6security.com/v1alpha1/movingtargetdefenses
Similarly, if you want to create a new object, you can use the POST method. You also need the object definition in JSON (usually working with kubectl requires yaml files, but in the background objects are always converted to JSON). Here is simple example to rotate the nginx servers in the default namespace in every 300 seconds (let’s name to mtd.json):
{
"apiVersion": "phoenix.r6security.com/v1alpha1",
"kind": "MovingTargetDefense",
"metadata": {
"name": "nginx-mtd",
"namespace": "default"
},
"spec": {
"podSelector": {
"app": "nginx"
},
"historyLenght": 5,
"strategy": {
"lifetimestrategy": "Constant",
"time": 300,
"action": "Delete"
}
}
}
Assuming you have “kubectl proxy” enabled on port 8001, the following curl command will create the object:
curl -X POST -d @mtd.json -H 'content-type: application/json' http://localhost:8001/apis/phoenix.r6security.com/v1alpha1/movingtargetdefenses
© 2022-2024 R6 Security Inc.
© 2019 R6Security
Follow us!
Follow us
© 2022-2024 R6 Security Inc.
© 2019 R6Security
© 2019 R6Security
© 2019 R6Security
Follow us!
Follow us!
Follow us!