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

     1  # What is a Kubefile
     2  
     3  ## Introduction
     4  
     5  Kubefile is a declaration for a set of kube-based applications and operations right after initiation of cluster.
     6  Content of Kubefile is composed of various instructions and arguments. These declarations define what kind of
     7  cluster-runtime and which applications will be packing together to distribute a user-specific cluster. Kubefile
     8  serves for building ClusterImages, and building is available on `linux platform only`. The reason for naming it
     9  as Kubefile is that the Kubefile contains a prefix 'Kube', which means that there are always Kubernetes-related
    10  binaries located in every ClusterImage. And Kubefile aims to provide editor a sense of defining applications
    11  based on taking k8s as kernel.
    12  
    13  ## Benefit
    14  
    15  Kubefile enables greater flexibility and portability of distributed applications.
    16  IT orgainizations take advantages fo Kubefiles to package distributed applications
    17  and their dependencies in a Kubernetes cluster that can run on premise, in public
    18  or private cloud, or on bare metal. Besides, Kubefile brings much more efficiency
    19  in distributed application delivery lifecycle.
    20  
    21  Without Kubefile, IT engineers take quite complicated steps to run distributed
    22  application(s). Taking a three-node etcd cluster without Helm as an example, IT engineers must
    23  prepare three nodes which meet the reprequisites of etcd installation, download
    24  and configure essential dependencies of etcd, and start to install and construct
    25  an etcd cluster. If etcd cluster is to be installed by Helm on an existing Kubernets,
    26  it could be shorten steps above without concerning about reprequisites and manually
    27  startup trigger. If there is no existing Kubernetes, Kubefile and ClusterImage are
    28  the best to choice to setup etcd cluster with one command just in minutes.
    29  
    30  ## Concept Origin
    31  
    32  Kubefile has quite similar concept with Dockerfile. And Kubefile is indeed inpired
    33  by Dockerfile. Actullay, Dockerfile encapsulates single-host application(s) into a single-host
    34  box(Docker image). While Kubefile encapsulates cluster-level distributed
    35  application(s) into a cluster-level box(ClusterImage).
    36  
    37  Docker uses Dockerfile to build Docker image, and run Docker container with Docker image.
    38  
    39  sealer uses Kubefile to build ClusterImage, and run Kubernetes cluster with ClusterImage.
    40  
    41  Docker tackles almost all of delivery issues of single-host application(s). sealer expands
    42  the concept to cluster level, and mostly focus on the perspetives of distributed application(s).
    43  To be specific, since Kubefile contains a Kubernetes cluster inside of itself by deault and
    44  Kubernetes has powerful ability to manage containers from Dockerfiles, we can say that
    45  Kubefile's concept in built on the basis of Dockerfile, Kubernetes.
    46  
    47  ## Kubefile Command Syntax
    48  
    49  The recommend commands in Kubefile are as following:
    50  
    51  ```
    52  FROM [scratch/kubernetes:v1.19.8] (specify a base image)
    53  CNI  (specify a CNI to be deployed in cluster)
    54  CSI  (specify a CSI to be deployed in cluster)
    55  APP  (declare apps to install)
    56  LAUNCH [applist]
    57  ```
    58  
    59  `CNI`, `LAUNCH` are allowed to be declared once.
    60  
    61  `APP`, `CSI` are allowed to be declared many times.
    62  
    63  The further introductions for command as follows:
    64  
    65  ### FROM
    66  `FROM` allows user to define the base image. User is able to do some incremental operations on
    67  base image.
    68  
    69  base image could be any of cluster image or scratch.
    70  
    71  ### CNI(Unrealized)
    72  
    73  `CNI` allows user to define which CNI to be installed over Kubernetes.
    74  
    75  Some behaviors are available:
    76  
    77  `CNI --type calico / flannel --cidr ...` an easiest way to deploy CNI, sealer will support several types of CNI.
    78  
    79  `CNI path / https://... / oss://`. `path` is a relative path refers to local build context, this can be a directory
    80  contains multiple yaml or a single yaml for deploying CNI. `https://...; oss://` are remote addresses for downloading related files to deploy CNI.
    81  
    82  ### CSI(Unrealized)
    83  
    84  `CSI` allows user to define which CSI to be installed over Kubernetes.
    85  
    86  Some behaviors are available:
    87  
    88  `CSI --type alibaba-cloud-csi-driver` an easiest way to deploy CSI, sealer will support several types of CSI.
    89  
    90  `CSI [path, https://, oss://]`. `path` is a relative path refers to local build context, this can be a directory
    91  contains multiple yaml or a single yaml for deploying CSI. `https://...; oss://` are remote addresses for downloading related files to deploy CSI.
    92  
    93  `[]` means user could declare several sources
    94  
    95  ### APP
    96  
    97  `APP` allows user to specify which applications to be installed over Kubernetes.
    98  
    99  The `APP` instruction has one form:
   100  
   101  `APP APP_NAME scheme:path1 scheme:path2`.
   102  
   103  The `APP_NAME` is a unique name to kube image.
   104  
   105  The `scheme` has three forms:
   106  
   107  * `local://path_rel_2_build_context` (files are from build context, path is relative to build context)
   108  * `http://example.yaml`
   109  * `https://example.yaml`
   110  * `helm://` (unrealized)
   111  
   112  There can be many `APP` in a `Kubefile`.
   113  
   114  ### LAUNCH
   115  
   116  `LAUNCH` allows user to specify which apps(specified by instruction `APP`) to start right after the completion of cluster initiation.
   117  Users are able to declare which applications to launch within the sealer image.
   118  
   119  The `LAUNCH` instruction has one form:
   120  
   121  `LAUNCH APP_1 APP_2`
   122  
   123  `LAUNCH ["APP_1", "APP_2"]`
   124  
   125  There are two behaviors for `LAUNCH`:
   126  
   127  * `helm install APP_1 APP_1_PATH_REL_2_Rootfs` (APP_1 is detected as helm app)
   128  * `kubectl apply -f APP_2_PATH_REL_2_Rootfs` (APP_2 is detected as raw yaml set app)
   129  
   130  The behaviors will be generated automatically, users don't have to care about that.
   131  
   132  There can be only one `LAUNCH` or `CMDS` instruction in a `Kubefile`.
   133  
   134  ### CMDS
   135  
   136  `CMDS` allows user to specify the self-defined executing commands at a cluster startup.
   137  
   138  The `CMDS` instruction has one form:
   139  
   140  `CMDS ["cmd1", "cmd2"]`
   141  
   142  symbol `""` is necessary for `CMDS` instruction.
   143  
   144  There can be only one `LAUNCH` or `CMDS` instruction in a `Kubefile`.