Bundle Repo Guidelines - padogrid/padogrid GitHub Wiki

◀️ Using Bundle Templates :link: User Bundle Catalogs ▶️

A bundle repo can be organized in any way you prefer but it must be constructable by Maven. Let's use the bundle, bundle-geode-1-app-perf_test_wan-cluster-ln-ny, as our example.

bundle-geode-1-app-perf_test_wan-cluster-ln-ny
├── apps
│   └── perf_test_wan
│       ├── bin_sh
│       │   └── build_app
│       ├── etc
│       ├── pom.xml
│       └── README.md
├── assembly-descriptor.xml
├── clusters
│   ├── ln
│   │   ├── bin_sh
│   │   └── etc
│   └── ny
│       ├── bin_sh
│       └── etc
├── images
│   ├── visio
│   │   └── wan-ny-ln.vsd
│   └── wan-ny-ln.png
├── LICENSE
├── pom.xml
├── README.md
├── README_HEADER.md
├── required_products.txt
└── target
    ├── archive-tmp
    └── assembly
        ├── bundle-geode-1-app-perf_test_wan-cluster-ln-ny.tar.gz
        └── bundle-geode-1-app-perf_test_wan-cluster-ln-ny.zip

Every bundle repo must consist of the following:

  • It must provide pom.xml along with an assembly descriptor that generates the final build tarball in the target/assemly directory. The tarball name must be the repo name followed by the .tar.gz extension.
    • Our example repo provides the pom.xml and assembly-descriptor.xml files. The mvn package command generated the tarball, target/assembly/bundle-geode-1-app-perf_test_wan-cluster-ln-ny.tar.gz. Our tarball contents are listed below.
drwxr-xr-x PADOGRID\dpark/0  0 2020-03-31 15:45 apps/
drwxr-xr-x PADOGRID\dpark/0  0 2020-04-11 10:11 apps/perf_test_wan/
drwxr-xr-x PADOGRID\dpark/0  0 2020-04-11 10:01 apps/perf_test_wan/bin_sh/
drwxr-xr-x PADOGRID\dpark/0  0 2020-03-31 15:45 apps/perf_test_wan/etc/
-rw-r--r-- PADOGRID\dpark/0 1060 2020-04-11 10:00 apps/perf_test_wan/bin_sh/.addonenv.sh
-rw-r--r-- PADOGRID\dpark/0 1585 2020-04-11 10:01 apps/perf_test_wan/bin_sh/build_app
-rw-r--r-- PADOGRID\dpark/0  697 2020-04-11 10:01 apps/perf_test_wan/bin_sh/setenv.sh
-rw-r--r-- PADOGRID\dpark/0  869 2020-04-11 10:01 apps/perf_test_wan/bin_sh/test_group
-rw-r--r-- PADOGRID\dpark/0  946 2020-04-11 10:01 apps/perf_test_wan/bin_sh/test_ingestion
-rw-r--r-- PADOGRID\dpark/0  872 2020-04-11 10:01 apps/perf_test_wan/bin_sh/test_tx
-rw-r--r-- PADOGRID\dpark/0 3396 2020-03-31 15:45 apps/perf_test_wan/etc/client-cache.xml
-rw-r--r-- PADOGRID\dpark/0  117 2020-03-31 15:45 apps/perf_test_wan/etc/client-gemfire.properties
-rw-r--r-- PADOGRID\dpark/0 8414 2020-03-31 15:45 apps/perf_test_wan/etc/group-factory.properties
-rw-r--r-- PADOGRID\dpark/0 6081 2020-03-31 15:45 apps/perf_test_wan/etc/group-get.properties
-rw-r--r-- PADOGRID\dpark/0 7366 2020-03-31 15:45 apps/perf_test_wan/etc/group-put.properties
-rw-r--r-- PADOGRID\dpark/0 6053 2020-03-31 15:45 apps/perf_test_wan/etc/group.properties
-rw-r--r-- PADOGRID\dpark/0 5140 2020-03-31 15:45 apps/perf_test_wan/etc/ingestion.properties
-rw-r--r-- PADOGRID\dpark/0  799 2020-03-31 15:45 apps/perf_test_wan/etc/log4j2.properties
-rw-r--r-- PADOGRID\dpark/0 5112 2020-03-31 15:45 apps/perf_test_wan/etc/tx.properties
-rw-r--r-- PADOGRID\dpark/0 3080 2020-04-11 10:00 apps/perf_test_wan/pom.xml
-rw-r--r-- PADOGRID\dpark/0 16702 2020-04-11 10:11 apps/perf_test_wan/README.md
drwxr-xr-x PADOGRID\dpark/0     0 2020-04-11 10:01 apps/perf_test_wan/bin_sh/
drwxr-xr-x PADOGRID\dpark/0     0 2020-03-31 15:45 clusters/
drwxr-xr-x PADOGRID\dpark/0     0 2020-03-31 15:45 clusters/ln/
drwxr-xr-x PADOGRID\dpark/0     0 2020-04-11 10:12 clusters/ln/bin_sh/
drwxr-xr-x PADOGRID\dpark/0     0 2020-03-31 15:45 clusters/ln/etc/
drwxr-xr-x PADOGRID\dpark/0     0 2020-03-31 15:45 clusters/ny/
drwxr-xr-x PADOGRID\dpark/0     0 2020-04-11 10:12 clusters/ny/bin_sh/
drwxr-xr-x PADOGRID\dpark/0     0 2020-03-31 15:45 clusters/ny/etc/
-rw-r--r-- PADOGRID\dpark/0  2075 2020-04-11 10:12 clusters/ln/bin_sh/setenv.sh
-rw-r--r-- PADOGRID\dpark/0  3574 2020-03-31 15:45 clusters/ln/etc/cache.xml
-rw-r--r-- PADOGRID\dpark/0  2884 2020-03-31 15:45 clusters/ln/etc/cluster.properties
-rw-r--r-- PADOGRID\dpark/0   195 2020-03-31 15:45 clusters/ln/etc/gemfire.properties
-rw-r--r-- PADOGRID\dpark/0  1817 2020-03-31 15:45 clusters/ln/etc/hibernate.cfg-mysql.xml
-rw-r--r-- PADOGRID\dpark/0  1777 2020-03-31 15:45 clusters/ln/etc/hibernate.cfg-postgresql.xml
-rw-r--r-- PADOGRID\dpark/0   778 2020-03-31 15:45 clusters/ln/etc/log4j2.properties
-rw-r--r-- PADOGRID\dpark/0    92 2020-03-31 15:45 clusters/ln/etc/prometheus.yml
-rw-r--r-- PADOGRID\dpark/0  2075 2020-04-11 10:12 clusters/ny/bin_sh/setenv.sh
-rw-r--r-- PADOGRID\dpark/0  3810 2020-03-31 15:45 clusters/ny/etc/cache.xml
-rw-r--r-- PADOGRID\dpark/0  2885 2020-03-31 15:45 clusters/ny/etc/cluster.properties
-rw-r--r-- PADOGRID\dpark/0   195 2020-03-31 15:45 clusters/ny/etc/gemfire.properties
-rw-r--r-- PADOGRID\dpark/0  1817 2020-03-31 15:45 clusters/ny/etc/hibernate.cfg-mysql.xml
-rw-r--r-- PADOGRID\dpark/0  1777 2020-03-31 15:45 clusters/ny/etc/hibernate.cfg-postgresql.xml
-rw-r--r-- PADOGRID\dpark/0   778 2020-03-31 15:45 clusters/ny/etc/log4j2.properties
-rw-r--r-- PADOGRID\dpark/0    92 2020-03-31 15:45 clusters/ny/etc/prometheus.yml

  • The tarball must contain the components that are fully operational. Components can be fully or partially built. If partially built, then it must provide the bin_sh/build_app script, which if executed, fully builds the component. For our example, this script is included for the perf_test_wan app (apps/perf_test_wan/bin_sh/build_app).

  • Each component must be placed in their component type directory. PadoGrid currently supports the following component type directory names.

    • apps
    • clusters
    • docker
    • groups
    • k8s
    • pods

  • The top level of the tarball must contain only directories. Files are not permitted. Note that our example tarball contains the apps and clusters directories at the top level and no files. These directories are the exact copies of the apps and clusters directories found in the repo.

  • Unsupported component types (or directories) are allowed in the tarball but keep in mind that PadoGrid is not aware of your custom component types. Custom component types should always accompany scripts to help users in navigating and managing them. If you are unsure of adding custom component types then place your components in the apps directory.

  • The repo must include the READEME.md file that provides bundle descriptions and installation instructions. This file is shown in the browser when you execute show_bundle bundle-geode-1-app-perf_test_wan-cluster-ln-ny.

  • The README_HEADER.md is optional. It should include short descriptions of the bundle displayable by the show_bundle -header command. If this file does not exist, then the first paragraph of the README.md file is used as the header.

README.md

The README.md file should have the following sections:

[Header Descriptions]

[## Installing Bundle]

[## Use Case]

[## Build Steps]

. . .

[## Startup Sequence]

[## Teardown]

  • The Header Descriptions section contains a short description of the bundle.

  • The Installing Bundle section contains commands to install the bundle. In most cases, this section would show the install_bundle command.

  • The Use Case section contains a data-flow or architecture diagram describing the bundle.

  • After the Use Case section, add details and instructions.

  • The Tearing Down section should include commands for shutting down the bundle and releasing system resources. This section should be the last section or thereabout.

required_products.txt

This file must contain a list of required products and their versions following the Relaxed Conventions.

◀️ Using Bundle Templates :link: User Bundle Catalogs ▶️