Package: sentinelc-appfeed
SentinelC App LibraryTooling used to validate, create and publish an app libary feed for the SentinelC platform.Published applications are importable into a SentinelC cloud controller, browsable in the web app and deployable to appliances using a simple click-through form.For an example structure of an app libary that uses the tooling provided by this project, seeDemo App Library.Specification of an app library structureGeneral files hierarchymanifests/: Contains all appsapp1: Unique name of the appapp1.yml: Top-level header. App descriptionapp1-fr.yml: Optional translationREADME.md: Full description of the appREADME-fr.md: Translated full descriptionversions/: List of versions1.0.0/: A specific versionapp1_1.0.0.kube.yml: Kubectl with placeholdersapp1_1.0.0.yml: Infos, parameters and architecturesapp1_1.0.0-fr.yml: Translation of ^1.0.1/...app2...Description file{app}.yml in the root of the manifestThe description file (app1.yml) contains the most basic information about the app. Theses are the following :display_name: Application name (translatable)description: Short description of the app (translatable)homepage: Official URL of the app.documentation: Optional URL of the app's documentation.category: Tag used to categorize the app.deprecated: True to indicate the app is no longer supported. Defaults to false.App README.mdFor a full description, a readme can be added and a translation can be provided using a -lang suffix.Version file{app}_{version}.yml in the versions/ folderThe version file (app1_1.0.0.yml) contains data specific to the version. There are two top-level keys:infosandvars.Basic example:infos:architectures:-amd64-arm64vars:var_key:label:Test varports:port_key:port:80architecturesList of compatible/supported architectures. Possible values:amd64arm64This indicates that all the images used in the recipe are published to the registry using all the specified architectures.
Seehttps://www.docker.com/blog/multi-arch-build-and-images-the-simple-way/for more details.VariablesThis is used to parameterize the individual instances of the application that will be deployed.Anything that must or can differ from an instance to another should be defined as a variable.Field nameTypeValid valuesDefaultNoteskeyString[a-z_]+Name used inside the kube template.typeStringtext, checkbox, number, password, email, url,  textarea.textCheck the next table to learn more.labelTranslatableCapitalized keyThe field label to display in the user form.descriptionTranslatableHelp text for the field. OptionalrequiredBooleanfalseField cannot be empty. If type is checkbox, it must be checked.regexpStringPython regular expressionnoneValue must match the regexp. See django RegexpValidatordefaultStringemptyA default value. Can be in function(param) format. See supported default functions.autoBooleanfalseIndicates this field is fully auto-generated using thedefaultfield.secretBooleanfalseIndicates this field is not visible to the user. If auto is false, it is user-provided on creation only, then hidden. If auto is true, it is not visible to the user at all.immutableBooleanfalseThe value cannot be changed after creation of the service. This is implied if auto is true.reveal_onceBooleanfalseIndicates if a secret field should be revealed during the pod creation process.Here is listed all "type" fields. All inputs are strings and some are converted during the creation of the template.ValueType returnedNoteCheckboxBoolReturns yaml bool "true" if ticked, else "false". If required, must be ticked.EmailStringAny acceptable email as per defined inRFC 3696-3URLStringAny acceptable url as perRFC 1034&RFC 1738. Must use HTTP or HTTPS protocol.NumberFloatAccepts any decimal number and returns a float.textStringAny string.textareaStringAny string, including newlines\n.PasswordStringAny string.Variable example: Most basicvars:my_var:Gests expanded to:vars:my_var:type:textlabel:My vardescription:nullrequired:falseregexp:nulldefault:""auto:falsesecret:falseimmutable:falseVariable example: A default/initial password that the user can overridevars:initial_admin_password:description:The initial admin user password you will use to connect to the admin panel after installation.required:truedefault:random_hex(12)immutable:trueVariable example: A default/initial password that the user can see but not changenote: immutable is implied to true for all auto field.vars:initial_admin_password:description:Use this password to login the admin panel for the first time.auto:truedefault:random_hex(12)Variable example: An internal secret that the user does not need to know aboutvars:mysql_password:auto:truedefault:random_hex(32)secret:trueVariable example: An initial password that the user can see and override on creation onlySinceautois not set to true, the user will be asked to fill the field even ifsecretis true.vars:initial_password:default:random_hex(32)secret:trueimmutable:truePortsThis is used to identify which port to expose.Ports won't be listed on install if not specified in the recipe.Field nameTypeValid valuesDefaultNoteskeyString[a-z_]+Name of the functionality linked to the port.portInt80Port numberprotocolString"TCP","UDP""TCP"Protocol used for communication.descriptionTranslatableBrief description of fonctionality.expose_vlanString"true","false","never""false"Indicate if port is visible to vlan. "never" hides choice on install.expose_cloudString"true","false","never""never"Indicate if port is visible through cloud. "never" hides choice on install. Notes : only http traffic will be forwarded.Variable example: Most basicports:app:port:80Gests expanded to:ports:app:port:80protocol:"TCP"description:nullexpose_vlan:"false"# Can be changed on installexpose_cloud:"never"# "never" can't be changed on installKube template file{app}_{version}.kube.yml in the version folderThe kube file (app1_1.0.0.kube.yml) contains the yaml description of the pod with placeholders.The file is in jinja2 template format.Using this toolLocally using dockerOfficial docker images are published on each release of this repository to the gitlab.com docker registry.Run the image using a command such as:cd my-app-feed/
docker run --rm -it -v .:/mnt/work registry.gitlab.com/sentinelc/app-library-builder:v1.5.3 bash
cd /mnt/work
applib-builder --helpOnce inside the container, all the applib-* tools will be available (see below).Locally using a python virtual envThe tools are also published to PyPi:https://pypi.org/project/sentinelc-appfeed/A common way to install them would be to use a virtual env.python3-mvenvenvsourceenv/bin/activate
pipinstallsentinelc-appfeedcd/some/where/my-app-feed/
applib-builder--helpAutomate with gitlab-ci in a custom app libraryIt is possible to fully automate the validation, build and publishing steps for your custom app feed.Thedemo repositorycontains a.gitlab-ci.ymlfile you can use as a starting point.Forking the demo repository is an easy way to get started. Otherwise, copy the.gitlab-ci.ymland add your own manifests.Once your final JSON feed is published, you will need to subscribe your SentinelC cloud controller to your custom app feed:https://sentinelc.com/docs/technical-guides/service-libraryList of toolsAll tools have a help section by using the -h or --help flag.applib-builderCreatesaJSONfilecontainingthevalidappslocatedinsidethemanifestfolderhowtouse-------------`applib-builder`Createsafeedbasedonthe./manifestfolderandoutputthefeedas./feed/demo-feed.yml`applib-builder-pnewmanifest-ocustomfeed-ffeed.yml`Createsafeedbasedonthe./newmanifestfolderandoutputthefeedas./customfeed/feed.ymlapplib-validatorValidatesthefolderhiearchyandvaluesofaspecificappinthemanifesthowtouse------------`applib-validatornewapp`Validatesthe`newapp`applocatedinsidethe./manifestsfolder`applib-validator-pnewmanifestnewapp`Validatesthe`newapp`applocatedinsidethe./newmanifestfolderapplib-runnerCreatesaYamlfilethatcanbe'run with podman using "podman play kube {file}"'howtouse------------`applib-runnernewapp1.0`Promptsthroughallparametersoftheapp`newapp`appversion1.0locatedinsidethe./manifestfolderthencreatethekuberneteconfigfile./out/newapp{timestamp}`applib-runnernewapp1.1-pnewmanifest-onewout-lfr`Promptsthroughallparametersofthe`newapp`appversion1.1,usingfrenchtranslations,locatedinsidethe./newmanifestfolderthencreatethekuberneteconfigfile./newout/newapp{timestamp}`applib-runnernewapp1.0-d`Createsthekuberneteconfigfile./out/newapp{timestamp}usingthedefaultvalueofeachparameter.applib-recipeCreatearecipe,eitherusingatemplateoranolderversionoftheapphowtouse------------`applib-recipenewapp1.0`Createsanappcallednewappinsidethe./manifestsfolderwithaversionfolder1.0thatuseourapptemplate`applib-recipe-pnewmanifestnewapp1.0`Createsanappcallednewappinsidethe./newmanifestfolderwithaversionfolder1.0thatuseourapptemplate`applib-recipe-pnewmanifestnewapp1.1-f1.0`Createsanewversionoftheapp`newapp`insidethe./newmanifestfolderwithaversionfolder1.1thatusetheversion1.0asabaseHow to create an appFirst add the templateYou can add the template by using our tools:to create a new app from scratch use theapplib-recipe {appname} {version}commandto create a new app version use theapplib-recipe {appname} {new_version} -f {old_version}Set it as your ownAll the files located inmanifests/{appname}are description files, you can fill them with the information found in the [description filed section](about:blank###Description file).Customize the version fileAll the files located inmanifests/{appname}/versions/versiondefinitions files. Edit them to get your app started.Add your kubectl with jinja variables to the{appname}_{version}.kube.yamlfileFill the{appname}_{version}.yamlfile with the information found in the [version file section](about:blank###Version file).Validate itOnce your app is set, use theapplib-validator newappcommand to validate your app.An error message will be displayed with the information to correct your app if necessary.Create a launchable testOnce your app is valid, you can useapplib-runner {appname} {version}command to create a runnable kube using the files of the repository.You can use the option-dto skip the prompts and use default values.Once the command is executed, you will find your executable yaml as./out/{appname}{timestamp}.yamlLaunch your app on a SentinelC deviceTo manually test your app on a sentinelC device before publishing your app, you will need toconnect to it via sshandcreate a zone.Write down your zone id, you will need it later.Connect to your device via ssh and copy the generated kube file on it.Use thepodman play kube --network network{vlan_id} --mac-address {random_unused_mac_address} {kubefile}.yamlcommand to launch your app. Once launched, use the network ports to find the IP of your service then add the port-forwarding rules.Connect via the device IP address either by being inside his vlan, connecting via the vpn or by the proxy.You can create new version of your app, upload it and update usingpodman play kube --replace {kubefile}.yamlNotes : You won't have to do any of these steps once the app is published to a JSON feed.