github.com/sealerio/sealer@v0.11.1-0.20240507115618-f4f89c5853ae/docs/design/Kubefile.md (about)

     1  # What is a Kubefile
     2  
     3  ## Introduction
     4  
     5  Kubefile is a script, composed of various commands(instructions) and arguments
     6  listed successively to automatically perform an action on a base ClusterImage in
     7  order to create(or form) a new ClusterImage. It is used by the sealer tool on
     8  only Linux platform for building ClusterImage. The reason of naming it as Kubefile,
     9  which contains the same prefix 'Kube' of Kubernetes, is that there is always
    10  a Kubernetes binary located in each ClusterImage. And when ClusterImage is ran from
    11  Kubefile, the built-in Kubernetes cluster will be setup and manage all infrastructure,
    12  and provide orchestration ability to upper applications.
    13  
    14  ## Benefit
    15  
    16  Kubefile enables greater flexibility and portability of distributed applications.
    17  IT orgainizations take advantages fo Kubefiles to package distributed applications
    18  and their dependencies in a Kubernetes cluster that can run on premise, in public
    19  or private cloud, or on bare metal. Besides, Kubefile brings much more efficiency
    20  in distributed application delivery lifecycle.
    21  
    22  Without Kubefile, IT engineers take quite complicated steps to run distributed
    23  application(s). Taking a three-node etcd cluster without Helm as an example, IT engineers must
    24  prepare three nodes which meet the reprequisites of etcd installation, download
    25  and configure essential dependencies of etcd, and start to install and construct
    26  an etcd cluster. If etcd cluster is to be installed by Helm on an existing Kubernets,
    27  it could be shorten steps above without concerning about reprequisites and manually
    28  startup trigger. If there is no existing Kubernetes, Kubefile and ClusterImage are
    29  the best to choice to setup etcd cluster with one command just in minutes.
    30  
    31  ## Concept Origin
    32  
    33  Kubefile has quite similar concept with Dockerfile. And Kubefile is indeed inpired
    34  by Dockerfile. Actullay, Dockerfile encapsulates single-host application(s) into a single-host
    35  box(Docker image). While Kubefile encapsulates cluster-level distributed
    36  application(s) into a cluster-level box(ClusterImage).
    37  
    38  Docker uses Dockerfile to build Docker image, and run Docker container with Docker image.
    39  
    40  sealer uses Kubefile to build ClusterImage, and run Kubernetes cluster with ClusterImage.
    41  
    42  Docker tackles almost all of delivery issues of single-host application(s). sealer expands
    43  the concept to cluster level, and mostly focus on the perspetives of distributed application(s).
    44  To be specific, since Kubefile contains a Kubernetes cluster inside of itself by deault and
    45  Kubernetes has powerful ability to manage containers from Dockerfiles, we can say that
    46  Kubefile's concept in built on the basis of Dockerfile, Kubernetes.
    47  
    48  ## Kubefile Example
    49  
    50  Kubefile is always located somewhere on a machine, or in a git repository. It can be placed with binaries, packages,
    51  YAML files and any others. And it can be placed alone as well. Since Kubefile is used to
    52  build a ClusterImage and ClusterImage represents distributed application(s), there must be
    53  something else which should be included except Kubefile. It is **building context**, the context of ClusterImage builing procedure.
    54  
    55  Here is a Kubefile folder example:
    56  
    57  ![image](https://user-images.githubusercontent.com/9465626/168005080-a9b47180-6284-484c-93bc-717e4e5f490f.png)
    58  
    59  There is a Kubefile and a `README.md` and `mysql-manifest.yaml` located in the
    60  folder. When a ClusterImage is being built, the folder context is called
    61  **building context**. In details, Kubefile has the following content:
    62  
    63  ```
    64  FROM kubernetes:v1.18.3
    65  COPY mysql-manifest.yaml .
    66  CMD kubectl apply -f mysql-manifest.yaml
    67  ```
    68  
    69  Like what we defined Kubefile at the top of this documentation, this Kubefile
    70  contains three commands. Every command follows Kubefile syntax. Here are
    71  brief illustration of these commands. `FROM kubernetes:v1.18.3` tells user that
    72  the building ClusterImage is from a `kubernetes:v1.18.3` ClusterImage, or based on
    73  `kubernetes:v1.18.3`. `COPY mysql-manifest.yaml .` means the building procedure
    74  should `COPY` a YAML file from the building context into the newly building
    75  ClusterImage. `CMD kubectl apply -f mysql-manifest.yaml` sets an executable
    76  command of the ClusterImage, and when the ClusterImage runs up, the command will
    77  be executed automatically. For more commands type illustration, please refer
    78  to Kubefile Syntax.
    79  
    80  ## How to use Kubefile
    81  
    82  It is quite easy for engineers to use Kubefile. Just one command of `sealer build -f KUBEFILE_PATH .`.
    83  sealer is the tool which applies Kubefile and builds a ClusterImage from Kubefile.
    84  In details, when engineer executes `sealer build` command, sealer binary will
    85  start to run as a process, pass on demand building context into process context,
    86  create a layer of OCI-compatible image for each command, and finally merge all
    87  layers to be a complete ClusterImage. The ClusterImage could be stored locally and
    88  pushed to remote image registries as well. In a word, engineer can use Kubefile
    89  to build ClusterImage. Only ClusterImage can be run to organize a cluster directly.
    90  
    91  ## Kubefile Command Syntax
    92  
    93  In the Kubefile example above, there are three kinds of Kubefile command type:
    94  `FROM`, `COPY`, `CMD`. Actually there are much more command types in Kubefile
    95  syntax. For more details about Kubefile command syntax, please refer to [Kubefile Command Syntax].