Skip to content

Commit

Permalink
docs: reorganize quickstart and home pages (#1393)
Browse files Browse the repository at this point in the history 
**Issue number:** https://splunk.atlassian.net/browse/ADDON-68816

## Summary

### Changes

> Please provide a summary of what's being changed

### User experience

> Please describe what the user experience looks like before and after
this change

## Checklist

If your change doesn't seem to apply, please leave them unchecked.

* [ ] I have performed a self-review of this change
* [ ] Changes have been tested
* [ ] Changes are documented
* [ ] PR title follows [conventional commit
semantics](https://www.conventionalcommits.org/en/v1.0.0/)

---------

Co-authored-by: Kamil Kędziak <[email protected]>
Co-authored-by: Artem Rys <[email protected]>
Co-authored-by: abogusz0 <[email protected]>
  • Loading branch information
@annabog0 @kkedziak-splunk
@artemrys @abogusz0
4 people authored Nov 12, 2024
1 parent 0513fbf commit 8ccdc0a
Show file tree
Hide file tree
Showing 6 changed files with 220 additions and 259 deletions.
111 changes: 111 additions & 0 deletions docs/commands.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
# Commands

These are the commands that are available in UCC framework.

## `ucc-gen build`

The `ucc-gen build` command builds the add-on. As of now, running `ucc-gen` does the same thing as running `ucc-gen build`,
but eventually calling `ucc-gen` without specifying a subcommand will be
deprecated.

It takes the following parameters:

* `--source` - [optional] folder containing the `app.manifest` and app
source. The default is `package`.
* `--config` - [optional] path to the configuration file. It defaults to
the globalConfig file in the parent directory of the source provided.
Only *.json* and *.yaml* files are accepted.
* `--ta-version` - [optional] override current version of TA. The default
version is version specified in `globalConfig.json` or `globalConfig.yaml`.
A Splunkbase compatible version of SEMVER is used by default.
* `-o` / `--output` - [optional] output folder to store the build add-on.
By default, it is saved in the `current directory/output` folder.
Absolute paths are accepted as well.
* `--python-binary-name` - [optional] Python binary name to use when
installing Python libraries. The default is `python3`.
* `-v` / `--verbose` - [optional] shows detailed information about
created/copied/modified/conflict files after build is complete.
This option is in the experimental mode. The default is `False`.
* `--pip-version` - [optional] pip version that is used to install python libraries. The default is `latest`.
* `--pip-legacy-resolver` - [optional] Use old pip dependency resolver by adding flag '--use-deprecated=legacy-resolver'
to pip install command. The default is`False`.
>**NOTE:** This flag is deprecated and will be removed from pip in the future.
Instead of using this flag, the correct solution would be to fix the packages your project depends on to work properly with the new resolver. Additionally, this flag is not compatible with pip version `23.2`. Use `23.2.1` instead.
* `--ui-source-map` - [optional] if present generates front-end source maps (.js.map files), that helps with code debugging.

### Verbose mode

The verbose mode is available for `v5.35.0` and later.

Running `ucc-gen build -v` or `ucc-gen build --verbose` prints additional information about
what was exactly created / copied / modified / conflicted after the build is complete. It does
not scan the `lib` folder due to the nature of the folder.

See the following description of what each state means:

* `created`: the file is not in the original package and was created during the build process.
* `copied`: the file is in the original package and was copied during the build process.
* `modified`: the file is in the original package and was modified during the build process.
* `conflict`: the file is in the original package and was copied during the build process, but may be generated by UCC itself, so incorrect usage can stop the add-on from working.

## `ucc-gen init`

`ucc-gen init` initializes the add-on. This is available on `v5.19.0` and later.
The `ucc-gen init` command initializes the add-on and bootstraps some code in the
modular input which you, as a developer, can extend for your needs.

Apart from standard files needed for the add-on, it also adds search head
clustering files in the `default/server.conf` file and reload triggers in the
`default/app.conf` file. Those files will be soon generated automatically by the
`ucc-gen build` command itself.
during the add-on development.

It takes the following parameters:

* `--addon-name` - [required] add-on name. See the
[official naming convention guide](https://dev.splunk.com/enterprise/docs/releaseapps/splunkbase/namingguidelines/).
* `--addon-rest-root` - [optional] add-on REST root, defaults to `--addon-name` if not provided.
* `--addon-display-name` - [required] add-on "official" name.
* `--addon-input-name` - [required] name of the generated input.
* `--addon-version` - [optional] version of the generated add-on, with `0.0.1` by default.
* `--overwrite` - [optional] overwrites the already existing folder.
By default, you can't generate a new add-on to an already existing folder.

## `ucc-gen import-from-aob`

Import from AoB (Add-on Builder), from `v5.24.0` and later. It is in the
**experimental** state as of now, meaning that running this command may not
produce a 100% UCC compatible add-on, but we are going to work on future
improvements for the script itself.

> **Note:** the `import-from-aob` command does not currently support Windows.
The import functionality is based on the
[ucc_migration_test](https://github.com/tmartin14/ucc_migration_test) bash
script.
One of the ways you can use it is to download an AoB-based add-on from
Splunkbase, unarchive the folder, and then use
`ucc-gen import-from-aob --addon-name <unarchived-folder-name>`. Or you can
run the same command against your locally developed add-on, but it should be
exported from AoB.

It accepts the following parameters:

* `--addon-name` - [required] add-on name.

## `ucc-gen package`

`ucc-gen package` can be used for `v5.30.0` and later. It packages the add-on so it can be installed.
It mimics the basics of the `slim package` command. This command can be used for most of the simple cases.

It does not support:

* the `.slimignore` file.
* the [dependencies section](https://dev.splunk.com/enterprise/docs/releaseapps/packageapps/packagingtoolkit/#Dependencies-section).

It accepts the following parameters:

* `--path` - [required] path to the built add-on (should include the `app.manifest` file).
* `-o` / `--output` - [optional] output folder to store the packaged add-on.
By default, it will be saved in the `current directory` folder.
It accepts absolute paths as well.
25 changes: 11 additions & 14 deletions docs/dot_conf_files.md
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,41 @@
# .conf files

`ucc-gen` generates the following `.conf` files in the `default` directory.
If any of the `.conf` files are present in the source directory, `ucc-gen` will
just copy that file to the output folder. The only exception is the `app.conf` file.
`ucc-gen build` generates the following `.conf` files in the `default` directory.
If any of the `.conf` files are present in the source directory, `ucc-gen` copies that file to the output folder. The only exception is the `app.conf` file.

> Note: for most of the use cases, the generated configuration is sufficient. If you
> need to adjust the file being generated, please ping us for a feature
> For most of the use cases, the generated configuration is sufficient. If you
> need to adjust the file that is generated, contact Splunk with a feature
> request. Alternatively, create a file in the `default` location, so it will accepted
> without being generated.
## `app.conf`

`ucc-gen` will merge the file present in the `default` folder with some
`ucc-gen` merges the file present in the `default` folder with some
additional information generated during the build time. But if you don't need
anything specific generated, you don't need to have `app.conf` in the source folder.

app.conf uses the `app.manifest` file to determine the add-on description, the add-on name,
the add-on title, and the add-on author (taking the first one if multiple are defined).
Make sure that your `app.manifest` is up-to-date, so `app.conf` will have all relevant information.

Also, the `triggers` stanza will be created by `ucc-gen`. It will determine what
Also the `triggers` stanza is created by the `ucc-gen build` command. `ucc-gen build` determines what
the `.conf` files are used in the add-on and generates the relevant key-value
pairs.

## `inputs.conf`

`ucc-gen` will generate a stanza for every input defined in the `globalConfig`
file and set `python.version` to `python3`.
`ucc-gen` generates a stanza for every input defined in the `globalConfig`
file and sets `python.version` to `python3`.

## `server.conf`

`ucc-gen` will generate the `shclustering` stanza, which will determine what
`ucc-gen` generates the `shclustering` stanza. This stanza determines which
`.conf` files are used in the add-on and generates the relevant key-value pairs.

## `web.conf`

`ucc-gen` will generate all needed information about the exposed endpoints
from the add-on.
`ucc-gen` generates information about the exposed endpoints from the add-on.

## `restmap.conf`

`ucc-gen` will generate all necessary information about the configuration of every
endpoint.
`ucc-gen` generates information about the configuration of every endpoint.
8 changes: 2 additions & 6 deletions docs/generated_files.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,9 @@
title: UCC framework generated files
---

# Generated files
The following table describes the files generated by UCC framework.

Below table describes the files generated by UCC framework

## File Description

| File Name | File Location | File Description |
| File name | File location | File description |
| ------------ | ------------ | ----------------- |
| app.conf | output/&lt;YOUR_ADDON_NAME&gt;/default | Generates `app.conf` with the details mentioned in globalConfig[meta] |
| inputs.conf | output/&lt;YOUR_ADDON_NAME&gt;/default | Generates `inputs.conf` and `inputs.conf.spec` file for the services mentioned in globalConfig |
Expand Down
60 changes: 25 additions & 35 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,49 +1,39 @@
# Overview
# About UCC

`splunk-add-on-ucc-framework` is a framework to generate UI-based Splunk
add-ons. It includes UI, REST handlers, Modular inputs, OAuth and Alert
action templates.
Universal Configuration Console (UCC) is a framework that simplifies the process of add-on creation for developers. You can use UCC to generate UI-based Splunk add-ons. UCC includes UI, REST handlers, modular inputs, OAuth, and alert action templates.

Only add-ons that use Python 3 are supported.
The UCC framework helps you to maintain consistency and a uniform look and feel across different add-ons. You can easily update and modify your add-ons.

It is available as a GitHub action here:
<https://github.com/splunk/addonfactory-ucc-generator-action>
The UCC framework is available as a GitHub action. See <https://github.com/splunk/addonfactory-ucc-generator-action>.

You can use [Splunk Extension for VSCode](https://marketplace.visualstudio.com/items?itemName=Splunk.splunk)
as well.
To work with UCC framework, you can also use Splunk Extension. It helps you to create, test, and debug the add-ons in a simple way. For more information, see [Visual Studio Code Extension for Splunk](https://marketplace.visualstudio.com/items?itemName=Splunk.splunk).

## What is UCC?
## Libraries

UCC stands for Universal Configuration Console. The purpose of having a
framework for add-on generation is to simplify the process of add-on
creation for developers. UCC 5 uses [SplunkUI](https://splunkui.splunk.com/),
which is a new UI framework based on React. The UCC UI repository can be found in the `ui` folder.
UCC-based add-ons are powered by the following Splunk libraries:

UCC-based add-ons are being powered by Splunk libraries:
[`solnlib`](https://github.com/splunk/addonfactory-solutions-library-python) and
[`splunktaucclib`](https://github.com/splunk/addonfactory-ucc-library). More
information [here](ucc_related_libraries.md).
* `solnlib`, see [https://github.com/splunk/addonfactory-solutions-library-python](https://github.com/splunk/addonfactory-solutions-library-python)
* `splunktaucclib`, see [https://github.com/splunk/addonfactory-ucc-library](https://github.com/splunk/addonfactory-ucc-library).

## Features
For more information, see [UCC-related libraries](ucc_related_libraries.md).

The `splunk-add-on-ucc-framework`:
> Note: Some specific Python libraries (such as `google-cloud-bigquery`) use `.so` files to operate. `pip` installs OS-specific versions of those `.so` files, which makes it impossible to use such add-ons on a Windows machine because it was built for macOS.
* generates UI (`appserver` folder).
* generates Python REST handlers to support UI CRUD operations (`bin` folder).
* generates [inputs](./inputs/index.md) and their [helper modules](./inputs/helper.md)
* generates OpenAPI description documents (`appserver/static/openapi.json` file) (for more information, see [here](openapi.md)).
* generates `.conf` files (more information, see [here](dot_conf_files.md)).
* installs Python requirements (`lib` folder).
* generate metadata files (`metadata` folder).
* generates the monitoring dashboard (for more information, see [here](dashboard.md)).
* it possibly extends the UI with custom codes (for more information, see [here](custom_ui_extensions/custom_hook.md)).
* it possibly extends the build process via a `additional_packaging.py` file (more information, [here](additional_packaging.md)).
* generates the necessary files defined for the Alert Action, if defined in globalConfig (for more informaiton, see [here](alert_actions/index.md)).
## What UCC generates

## Installation
When you use UCC to create an add-on, the following elements are generated and stored in the appropriate folders:

`splunk-add-on-ucc-framework` is available on [PyPI](https://pypi.org/project/splunk-add-on-ucc-framework/).
* UI is stored in the `appserver` folder,
* Python REST handlers that support UI CRUD operations are stored in the `bin` folder,
* inputs and their helper modules. For more information, see [Inputs](./inputs/index.md) and [Helper modules](./inputs/helper.md),
* OpenAPI description documents are stored in the `appserver/static/openapi.json` file. For more information, see [OpenAPI description document](openapi.md),
* `.conf` files. For more information, see [.conf files](dot_conf_files.md),
* Python requirements are installed in the `lib` folder,
* metadata files are stored in the `metadata` folder,
* the monitoring dashboard. For more information, see [Dashboard](dashboard.md),
* the necessary files defined for the alert action, if you defined the alert action in the `globalConfig` file. For more information, see [Alert actions](alert_actions/index.md).

## Caveats
You can extend your add-ons with the following files:

* Some specific Python libraries (such as `google-cloud-bigquery`) use `.so` files to operate. `pip` will install OS-specific versions of those `.so` files, which makes it impossible to use such add-ons on a Windows machine since it was built for macOS.
* to extend the UI, use custom codes. For more information, see [Custom hook](custom_ui_extensions/custom_hook.md).
* to extend the build process, use the `additional_packaging.py` file. For more information, see [additional_packaging.py file](additional_packaging.md).
Loading

0 comments on commit 8ccdc0a

Please sign in to comment.