Documentation Sina 2.7.x

KubeOps SINA #

How to use SINA #

This guide explains how to use SINA with detailed instructions and examples.

General commands #

Overview of all SINA commands #

sina:
  Sina is a SoftwareINstAller for kubernetes cluster

Usage:
  Sina [options] [command]

Options:
  --version         Show version information
  -?, -h, --help    Show help and usage information

Commands:
  login                    logs you in
  search                   Shows you all the available packages on the softwarehub
  build                    Creates your final sina.package
  push                     Push package.sina to KubeOps Hub.
  pull <package>           Downloads an existing package from the hub without installing.
  install <packagename>    install a .sina file and if it is required, download it
  update <packagename>     update a .sina file and if it is required, download it
  delete <packagename>     run delete section of a .sina file and if it is required, download it
  list                     List packages from storage
  lint                     lint your files for your .sina package
  create                   Creates a package.yaml and a template.yaml for you to manipulate
  create helm              creates a sina package with helm package.
  version                  Basic infos about SINA

Command ‘sina –help’ #

The command sina --help gives you an overview of all available commands:

[root@localhost ~]# sina --help

Alternatively, you can also enter sina or sina -? in the command line.

Command ‘sina version’ #

The sina version command shows you the current version of SINA.

[root@localhost ~]# sina version

The output should be:

[ 12/03/2021 10:13:20 Debug1  default ] Check OS Support...
[ 12/03/2021 10:13:20 Debug1  default ] set Loglevel info
Version: 2.7.1
This work is licensed under Creative Commons Attribution - NoDerivatives 4.0 International License(see https://creativecommons.org/licenses/by-nd/4.0/legalcode for more details).
©KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2022

The sina search command displays all available packages of your own private hub. Only the logged in user can see the packages on his private hub. The User column contains the name of the creator of the package.
The Name column contains the name of the package.
The Version column contains the version of the package.
The Description column contains the description of the package.
The Install column contains a string consisting of the name of the creator, name and version of the package. This string can be copied and used for the sina install command.

[root@localhost ~]# sina search --hub <hubname>

Example: User donald is logged in and wants to get the packets from his private hub:

[root@localhost ~]# sina search --hub donald
| User   | Name         | Version | Description                      |Install                    |
|--------|--------------|---------|----------------------------------|---------------------------|                  
| donald | private-sina | 0.0.1   | private installation             | donald/private-sina:0.0.1 |                                       
| donald | private-test | 0.0.1   | private package                  | donald/private-test:0.0.1 |
| donald | livedemo     | 2.7.2   | welcome to sina                  | donald/livedemo:2.7.1     | 

–ps flag #

The --ps parameter can be used to filter for keywords that refer to all five columns. It is also possible to filter by individual word components:

[root@localhost ~]# sina search --hub <hubname> --ps <name>

Example:
In this case, all packets containing the word private are displayed:

[root@localhost ~]# sina search --hub donald --ps private
| User   | Name         | Version | Description                      |Install                    |
|--------|--------------|---------|----------------------------------|---------------------------|                  
| donald | private-sina | 0.0.1   | private installation             | donald/private-sina:0.0.1 |                                       
| donald | private-test | 0.0.1   | private package                  | donald/private-test:0.0.1 |                                        

–hub flag #

In addition, there is an option to search for packages on a specific hub using the --hub parameter. You need no login to search in the public hub.

[root@localhost ~]# sina search --hub public
| User   | Name         | Version | Description                      |Install                  |
|--------|--------------|---------|----------------------------------|-------------------------|
| sina   | lima         | 0.6.2   | installs LIMA                    | sina/lima:0.6.2         |
| sina   | installation | 0.0.1   | sina create example package.yaml | sina/installation:0.0.1 |  
| donald | elk-sina     | 0.0.1   | ELK installation                 | donald/elk-sina:0.0.1   |
| donald | prod-test    | 0.0.1   | test for prod                    | donald/prod-test:0.0.1  | 
| lima   | lima         | 0.6.0   | installs LIMA                    | lima/lima:0.6.0         |
                                     

The parameters --hub and --ps can be combined for a targeted search in the sina hub:

[root@localhost ~]# sina search --hub <hubname> --ps <package_name>

Example:
The user sina wants to display all packages in the sina hub with the term “lima”.

[root@localhost ~]# sina search --hub sina  --ps lima
| User | Name         | Version | Description                      |Install                  |
|------|--------------|---------|----------------------------------|-------------------------|
| sina | lima         | 0.6.2   | installs LIMA                    | sina/lima:0.6.2         |
| sina | lima         | 0.7.1   | installs LIMA                    | sina/lima:0.7.1         |
                                     

Command ‘sina create’ #

Note: The command works in the current directory.

The command sina create creates four files (package.yaml, template.yaml, logo.png and docs.tgz) in the current directory. These files can be edited by the user.

The template.yaml is required if the template engine Scriban is to be used.

The logo.png is a package-thumbnail with the size of 50x50px

The docs.tgz is a zipped directory with the documentation of the package. The documentation of the package is written down in markdown. The file for the documentation is called readme.md.

Note: Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md).

[root@localhost ~]# sina create

Created files:

  • package.yaml
  • template.yaml
  • logo.png - For showing logo on the KubeOpsHub.
  • docs.tgz - For showing documentation on the KubeOpsHub.

Command ‘sina create helm’ #

The ‘sina create helm’ command creates a sina package with helm package.

After the command ‘create helm’ you must write the name of the folder where the file is to be created.

IMPORTANT: Make sure if the name of the folder you entered really exists

[root@localhost ~]# sina create helm <folder>
``

> This folder name is required.

Example:
The folder name `sina` specifies that the YAML package file will be created in Sina

```console
[root@localhost ~]# sina create helm sina 

Command ‘sina lint’ #

The sina lint command is used to check whether the contents of the package.yaml file are valid:

[root@localhost ~]# sina lint

Command ‘sina build’ #

Note: The command works in the current working directory.

Note: Name your package in the package.yaml in full lower case.

Note: Don´t change the name for logo.png and docs.tgz

Note: Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md).

IMPORTANT: Please name your packages without docker tags (:v1.0.0).

The sina build command creates the necessary yaml files for building a package:

[root@localhost ~]# sina build

All files specified in the package.yaml are combined together with the package.yaml to form a SINA package.

Command ‘sina login’ #

The sina login command logges on to the KubeOps services. The account name is required for this command.

Note: To push packages into the hub, you need to create an account here first.

After the flag -u type your username. Afterwards you will be asked to enter your password.

[root@localhost ~]# sina login -u <username>

The parameter -p is used to enter the password in the command directly, but it is important to know that the password will be shown in plain text. This parameter can help with the automation of SINA commands.

[root@localhost ~]# sina login -u <username> -p <password>

-u flag #

The -u parameter is used to specify the user name.

[root@localhost ~]# sina login -u

This parameter is required.

-p flag #

The -p parameter is used to specify the password.

[root@localhost ~]# sina login -p

This parameter is not required. We recommend to use this parameter only if it is absolutely necessary.

Command ‘sina logout’ #

The sina logout command logges out from the KubeOps services.

Note: To logout from the KubeOps services, you have to be logged in.

[root@localhost ~]# sina logout

Command ‘sina push’ #

The sina push command uploads SINA packages to the KubeOps Hub:

[root@localhost ~]# sina push --hub <hubname>

Note: In order to upload SINA packages, you first have to log in using the sina login command.

Note: The package name is case-sensitive and should be lowercase.

–hub flag #

The --hub parameter is used to upload SINA packages to a specific hub, e.g. in this example we are pushing our SINA package into the public hub.

[root@localhost ~]# sina push --hub public

Command ‘sina install’ #

The sina install command installs a SINA package:

[root@localhost ~]# sina install --hub <hubname> <package>

The string of the column Install in the output of sina search is required:

Example: The package livedemo of the user sina with version 2.7.1 is to be installed from the private Hub:

[root@localhost ~]# sina install --hub public sina/livedemo:2.7.1 

–hub flag #

The --hub parameter must be used to install packages from the software hub. Only the logged in user can install the packages from the software hub.

[root@localhost ~]# sina install --hub <hubname> <package>

Example: The package livedemo of the user sina with version 2.7.1 is to be installed from the public Software Hub:

[root@localhost ~]# sina install --hub public sina/livedemo:2.7.1

-p flag #

The “p” parameter must be used to install local packages. For “p” parameter you need no --hub:

[root@localhost ~]# sina install -p package.sina

-f flag #

The parameter f must be used to use yaml files from the user.

[root@localhost ~]# sina install <package> -f <user.yaml>

Example: The package livedemo of the user sina with version 2.7.1 is to be installed from the public software hub and user specific files are to be used for the installation:

[root@localhost ~]# sina install --hub public sina/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: The -f parameter can be specified any number of times to use any number of files. Note: The -f parameter can also be combined with the --hub parameter.

–namespace flag #

The namespace parameter can be used to specify a Kubernetes namespace in which the installation is to be performed.

[root@localhost ~]# sina install --hub <hubname> <package> --namespace <namespace>

Example: The package livedemo of the user sina with version 2.7.1 is to be installed from the public software hub and a custom kubernetes namespace is used:

[root@localhost ~]# sina install --hub public sina/livedemo:2.7.1 --namespace MyNamespace

Note: If no --namespace parameter is specified, the namespace default will be used.

–dname flag #

The parameter dname can be used to save the package under a specific name.

[root@localhost ~]# sina install --hub <hubname> <package> --dname <deploymentname>

Example: The package livedemo of the user sina with version 2.7.1 is to be installed from the public software hub and a deployment name is set:

[root@localhost ~]# sina install --hub public sina/livedemo:2.7.1 --dname MyDeployment

Note: If no --dname parameter is specified, a random deployment name will be generated.
Note: The deployment name is stored in the file /<user>/var/kubeops/sina/deployment.yaml.

Command ‘sina pull’ #

The sina pull command downloads a specific SINA package from the hub without installing it directly.

[root@localhost ~]# sina pull --hub <hubname> <packagename> -o <desired name>

Note: sina pull downloads the package to the current directory.

Note: The downloaded packages can be transferred to machines without internet access via USB, for example.

Note: The package name is case-sensitive and should be lowercase.

Example:

[root@localhost ~]# sina pull --hub public donald/sina-print-test:0.0.1 -o printpackage

Note: The -o option specifies a name that the package will have after download. The file automatically gets the .sina extension. The -o option is not optional.

–hub flag #

The --hub parameter is used to download SINA packages to a specific hub, e.g. in this example we are pulling our SINA package from the public hub.

[root@localhost ~]# sina pull --hub public donald/sina-print-test:0.0.1

-r flag #

The parameter r can be used to pull the docker images which are included in the package to a given local docker registry.

[root@localhost ~]# sina pull --hub <hubname> <packagename> -o <desired name> -r <local.docker.registry>

Note: sina pull downloads the package and pulls the required docker images to the given local docker registry.

Example:

[root@localhost ~]# sina pull --hub public donald/sina-print-test:0.0.1 -o printpackage -r 127.0.0.1:5000

Note: After the sina pull donald/sina-print-test:0.0.1 -o printpackage -r 127.0.0.1:5000 command you can use sina install -p printpackage.sina to use the docker image from your local docker registry.

Note: You can now install your packages including docker images without internet connection from your local machine.

Command ‘sina list’ #

The sina list command lists all installed SINA packages:

[root@localhost ~]# sina list
 SINA version: 2.7.1
| Deployment       | Package                | PublicHub |
|------------------|------------------------|-----------|
| sinaInstallsLima | sina/lima:0.6.2        | private   |
| sinaCreateTest   | sina/sina-create:0.0.1 | public    |

Command ‘sina update’ #

The sina update command updates an already installed SINA package:

For update, the installation and the update package have to be the same name. Update will be defined in the package.yaml.

[root@localhost ~]# sina update --hub <hubname> --dname <deploymentname> <package>

The string of the column Install in the output of sina search is required:

Example: The installation of the package lima from the user sina with version 0.6.2 and deployment name sinaInstallsLima is updated by a package from the private Software Hub from sina.:

[root@localhost ~]# sina update --hub public --dname sinaInstallsLima sina/sina/lima:0.6.2 

–hub flag #

The --hub parameter must be used to update packages from the software hub. Only the logged in user can update the packages from the software hub.

[root@localhost ~]# sina update --hub <hubname> <package>

Example: The package livedemo of the user sina with version 2.7.1 is to be updated from the public Software Hub:

[root@localhost ~]# sina update --hub public sina/livedemo:2.7.1
```create:0.0.1

-p flag #

The “p” parameter must be used to update the installation from a local package. For “p” parameter you need no --hub parameter:

[root@localhost ~]# sina update -p package.sina

-f flag #

The parameter f must be used to use yaml files from the user.

[root@localhost ~]# sina update --hub <hubname> <package> -f <user.yaml>

Example: The installation of the package livedemo of the user sina with version 2.7.1 is updated by a package from the public software hub and user specific files are to be used for the update progress:

[root@localhost ~]# sina update --hub public sina/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: The -f parameter can be specified any number of times to use any number of files. Note: The -f parameter can also be combined with the --hub parameters.

–namespace flag #

The namespace parameter can be used to specify a kubernetes namespace in which the update is to be performed.

[root@localhost ~]# sina update --hub <hubname> <package> --namespace <namespace>

Example: The installation of the package livedemo of the user sina with version 2.7.1 is updated by a package from the public software hub and a custom kubernetes namespace is used:

[root@localhost ~]# sina update --hub public sina/livedemo:2.7.1 --namespace MyNamespace

Note: If no --namespace parameter is specified, the default namespace will be used.

–dname flag #

The parameter dname can be used to update the deployment by name.

[root@localhost ~]# sina update --hub <hubname> <package> --dname <deploymentname>

Example: The installation of the package livedemo of the user sina with version 2.7.1 is updated by a package from the public software hub and a deployment name is set:

[root@localhost ~]# sina update --hub public sina/livedemo:2.7.1 --dname MyDeployment

Command ‘sina delete’ #

The sina delete command deletes an already installed SINA package:

For delete, the installation and the update package have to be the same name. Delete will be defined in the package.yaml.

[root@localhost ~]# sina delete --hub <hubname> --dname <deploymentname> <package>

The string of the column Install in the output of sina search is required:

Example: The installation of the package lima from the user sina with version 0.6.2 and deployment name sinaInstallsLima is deleted by a package from the private Software Hub from sina.:

[root@localhost ~]# sina delete --hub public --dname sinaInstallsLima sina/sina/lima:0.6.2 

–hub flag #

The --hub parameter must be used to use the delete section of packages from the software hub. Only the logged in user can use the delete section of packages from the software hub.

[root@localhost ~]# sina update --hub <hubname> <package>

Example: The package livedemo of the user sina with version 2.7.1 is to be updated from the public Software Hub:

[root@localhost ~]# sina update --hub public sina/livedemo:2.7.1
```create:0.0.1
```-create:0.0.1

-p flag #

The “p” parameter must be used to delete the installation from a local package. For “p” parameter you need no --hub parameter:

[root@localhost ~]# sina delete -p package.sina

-f flag #

The parameter f must be used to use yaml files from the user.

[root@localhost ~]# sina delete --hub <hubname> <package> -f <user.yaml>

Example: The installation of the package livedemo of the user sina with version 2.7.1 is deleted by a package from the public software hub and user specific files are to be used for the delete progress:

[root@localhost ~]# sina delete --hub public sina/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: The -f parameter can be specified any number of times to use any number of files. Note: The -f parameter can also be combined with the --hub parameter.

–namespace flag #

The namespace parameter can be used to specify a kubernetes namespace in which to perform the deletion.

[root@localhost ~]# sina delete --hub <hubname> <package> --namespace <namespace>

Example: The installation of the package livedemo of the user sina with version 2.7.1 is deleted by a package from the public software hub and a custom kubernetes namespace is used:

[root@localhost ~]# sina delete --hub public sina/livedemo:2.7.1 --namespace MyNamespace

Note: If no --namespace parameter is specified, the default namespace will be used.

–dname flag #

The parameter dname can be used to delete the deployment by name.

[root@localhost ~]# sina delete --hub <hubname> <package> --dname <deploymentname>

Example: The installation of the package livedemo of the user sina with version 2.7.1 is deleted by a package from the public software hub and a deployment name is set:

[root@localhost ~]# sina deleted --hub public sina/livedemo:2.7.1 --dname MyDeployment

Command ‘sina remove’ #

The sina remove command removes a SINA package from the hub:

Note: Only logged users can delete there own packages. Users must have write-permissions.

[root@localhost ~]# sina remove --hub <hubname> <package>

Note: The string of the column Install in the output of sina search is required:

Example: The package livedemo of the user sina with version 2.7.1 will be removed from the public hub:

[root@localhost ~]# sina remove --hub public sina/livedemo:2.7.1 

Note: If your package already deleted, the command will try do delete your package successfully. Deleting non-existing packages does not cause any errors.

.yaml Formats #

package.yaml #

This file defines properties of the SINA package. This file is created after the sina create command. The package.yaml defines a package in a specific version as well as the tasks needed to install it. The tasks which are used in the package.yaml are plugins, which can be created by the user. The includes.containers element is used for docker images. A container for the docker images will be created when the sina install, sina update or sina delete command is used. There is also a description, which will be shown in the sina search command. The includes.files element describes the files which are inluded in the SINA package. The installation.tasks tree describes the tasks (SINA plugins), which are executed with the sina install command. The update.tasks tree describes the tasks (SINA plugins), which are executed with the sina update command.The delete.tasks tree describes the tasks (SINA plugins), which are executed with the sina delete command.

IMPORTANT: The apiversion has been changed from …/user/v2 to …/user/v3. The Image Key has been split into to seperate Keys registry and image.

IMPORTANT: To get your package please enter a fully lowercase name for your package.

Note: Do not change name for logo.png and docs.tgz

Note: Please name your markdown files inside docs.tgz without versions (docs/documentation-1.0.0.md).

IMPORTANT: Please name your packages without docker tags (:v1.0.0).

apiversion: kubernative/kubeops/sina/user/v3 # Required field
name: sina-example-packagev3 # Required field
description: sina-example-package # Required field
version: 0.1.0 # Required field
includes:  # Required field: When "files" or "containers" are needed.
  files:  # Optional field: IF file is attached, e.g. "rpm, .extension"
    input: "template.yaml"
  containers: # Optional field: When "containers" are needed.
    example:
      registry: docker.io
      image: nginx
      tag: latest
docs: docs.tgz
logo: logo.png
installation: # Required field
  includes: # Optional field: When "files" or "containers" are needed.
    files: # Optional field:
      - input # Reference to includes
    containers: # Optional field:
      - example # Reference to includes
  tasks: 
    - cmd:
        command: "touch ~/sinaExample1"
update: # Required field
  includes: # Optional field: When "files" or "containers" are needed.
    files: # Optional field:
      - input # Reference to includes
    containers: # Optional field:
      - example # Reference to includes
  tasks:
    - cmd:
        command: "touch ~/sinaExample2"
delete: # Required field
  includes: # Optional field: When "files" or "containers" are needed.
    files: # Optional field:
      - input # Reference to includes
    containers: # Optional field:
      - example # Reference to includes
  tasks:
    - cmd:
        command: "rm ~/sinaExample1"
    - cmd:
        command: "rm ~/sinaExample2"

default.yaml #

The default.yaml in a package.sina is used for setting default variables. In case you use the -f parameter in install, update or delete, the file which you address is merged with the default.yaml. If you have the same keys but different values in both files, your adressed file will overwrite the values set by the dafault.yaml.

config.yaml #

Location for: /var/kubeops/sina/config.yaml

The config.yaml file contains all necessary files for networking and logging. For example, config.yaml contains the hub from which the packages are downloaded.

apiversion: kubernative/sina/config/v2           # Shows the supported API-Version
spec:                                            
hub: https://hub.kubernative.net/dispatcher/      # Adress to the SINA online hub
plugins: /kubeops/sina/sina-plugins/                      # Location of the SINA-Plugins
registry: registry1.kubernative.net/             # Registry, where Docker-images will be pulled to (sina pull)
workspace: /tmp/sina/process/                    # Workspace Path 
logging: info                                    # Loglevel options: info (default), warning, error, debug1, debug2, debug3
housekeeping: true                               # Housekeeping options: true (all temporary created folders will be deleted), false (all temporary created folders won't be deleted)

Usage #

To keep SINA running there has to be a valid config.yaml file.
After installing SINA, a valid config.yaml file is created under the location /var/kubeops/sina/config.yaml. If you want to use your own Hub you can create a user-specific config.yaml file. The original file can be changed too, but it is not recommended.

$KUBEOPSROOT Variable #

The $KUBEOPSROOT environment variable stores the location of the SINA plugins and the config.yaml. To use the variable, the config.yaml and the plugins have to be copied manually.
So for example:

cp -r /var/kubeops/sina/config.yaml /home/<user>/kubeopsrootdir/sina/config.yaml
rm -rf /var/kubeops/sina
cp -r /var/kubeops/plugins /home/<user>/kubeopsrootdir/plugins
rm -rf /var/kubeops/plugins

If you want to use the config file and plugins with a user you have to go through these steps.

How to use templating within the package.yaml #

This is an example of how templating in a package.yaml is working with sina 2.7.x

First we need to create this package.yaml:

apiversion: kubernative/kubeops/sina/user/v3
name: sina-template-example-packagev3
description: sina-template-example-package
version: 0.1.0
includes:
  files:
    input: "template.yaml"
    default: "default.yaml"
  containers:
    example:
      registry: docker.io
      image: nginx
      tag: latest

installation: 
  includes:
    files:
      - input
      - default
    containers:
      - example
  tasks: 
    - template:
       tmpl: {{package.includes.files.input}}
       target: {{values.target}}
update:
  includes:
    files:
      - input
      - default
    containers:
      - example
  tasks: 
    - template:
       tmpl: {{package.includes.files.input}}
       target: {{values.target}}
delete:
  includes:
    files:
      - input
      - default
    containers:
      - example
  tasks: 
    - template:
       tmpl: {{package.includes.files.input}}
       target: {{values.target}}

Now we create a template.yaml:

package:
  file: {{package.includes.files.input}}
  uservalues: {{values.exmaple}}

Next we create a default.yaml:

example: example
target: target.yaml

Please make sure that you create all these files in the same directory.

Now we are ready to create a sina package. For this we need the follwoing command:

sina build

Next we can run the installation section we have defined in the package.yaml with the following command:

sina install -p package.sina --dname example

We can check the result in the directory $KUBEOBSROOT/sina/tmp.

The file of interest is the target.yaml

the content of target.yaml is:

package:
  file: template.yaml
  uservalues: example

So what exactly happened?
In the package.yaml you can see that we use {{package.includes.files.input}} for defining the template.yaml as value for the key tmpl. You can use any value of the package.yaml but make sure that the path to the value is correct and starts with package.. This is the indicator for using a variable from the package.yaml.

You can also see that we use {{values.target}} for defining the target.yaml as value for the key target. If you wonder where the target.yaml is coming from you can check the default.yaml. If you want to use a variable from the default.yaml or from a file specified with the parameter -f make sure that the path to the value is correct and starts with values..

For more information about the template syntax check the Scriban documentation (https://github.com/scriban/scriban/blob/master/doc/language.md) and try it out in the online demo (https://scribanonline.azurewebsites.net/).

Plugins #

With the installation of SINA a handful of plugins are included. Which plugins are included can be seen under “pre-installed plugins” in the Plugin References