ibm-charts/ibm-app-navigator

IBM Application Navigator Helm Chart

Introduction

IBM Application Navigator is a tool that compliments the IBM Private Cloud console, providing visualization, inspection, and interaction with the deployed resources that comprise an application.

IBM Application Navigator is designed to satisfy a need identified by the Kubernetes Application Special Interest Group (SIG), who made the following observation and statement:  

The above description, from the [Kubernetes homepage](https://kubernetes.io/), is centered on containerized applications. Yet, the Kubernetes metadata, objects, and visualizations (e.g., within Dashboard) are focused on container infrastructure rather than the applications themselves. The Application CRD ([Custom Resource Definition](https://kubernetes.io/docs/concepts/api-extension/custom-resources/#customresourcedefinitions)) in the [Kubernetes Application](https://github.com/kubernetes-sigs/application) project aims to change that in a way that's interoperable between many supporting tools.

IBM Application Navigator provides visualization of all defined Applications, offering drill down into their respective comprised 'components'. Each component is a Kubernetes resource. Each Kubernetes resource has a 'Kind' - e.g. Deployment, Service, tWAS-App (a Kubernetes Custom Resource Definition), etc.. IBM Application Navigator offers action menu items by Kind. These menu items provide URLs and scripted commands that enable the user to navigate to, and operate, other tools in context - e.g. the log, monitor, trace, configuration page for the currently selected component.

### Resources Required

For each Docker container:
- CPU Requested : 500m (500 millicpu)
- Memory Requested : 512Mi (~ 537 MB)

Actual resource consumption will vary depending on usage. These numbers represent maximum requirements.  In practice, you will likely see lower consumption.  

### Storage

IBM Application Navigator is stateless and does not require any persistent volumes to operate.

### Chart Details

- Installs a `Deployment` running the IBM Application Navigator UI and REST API container as its backend.
- Installs a `Deployment` running the IBM Application Navigator Controller and REST API container as its backend.
- Installs a `Deployment` running the IBM Application Navigator WAS Controller.
- Installs a `Job` which executes the IBM Application Navigator Initialization container during chart installation.
- Installs a `Service` and optionally an `Ingress` to route traffic to the IBM Application Navigator UI.
- Installs multiple `ConfigMaps` that manage the configuration of IBM Application Navigator.

Note the IBM Application Navigator containers are configured to run on IBM Cloud Private's management node.

### Prerequisites

- IBM Cloud Private 3.1.2 or greater.
- A user with Cluster administrator role is required to install the chart.

### PodSecurityPolicy Requirements

This chart requires a PodSecurityPolicy to be bound to the target namespace prior to installation. Choose either a predefined PodSecurityPolicy or have your cluster administrator create a custom PodSecurityPolicy for you:

* Predefined PodSecurityPolicy name: [`ibm-restricted-psp`](https://ibm.biz/cpkspec-psp)
* Custom PodSecurityPolicy definition:

```yaml
apiVersion: extensions/v1beta1
kind: PodSecurityPolicy
metadata:
  name: ibm-app-navigator-psp
spec:
  allowPrivilegeEscalation: false
  forbiddenSysctls:
  - '*'
  fsGroup:
    ranges:
    - max: 65535
      min: 1
    rule: MustRunAs
  requiredDropCapabilities:
  - ALL
  runAsUser:
    rule: MustRunAsNonRoot
  seLinux:
    rule: RunAsAny
  supplementalGroups:
    ranges:
    - max: 65535
      min: 1
    rule: MustRunAs
  volumes:
  - configMap
  - emptyDir
  - projected
  - secret
  - downwardAPI
  - persistentVolumeClaim

• Custom ClusterRole for the custom PodSecurityPolicy:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ibm-app-navigator-psp-clusterrole
rules:
- apiGroups:
  - extensions
  resourceNames:
  - ibm-app-navigator-psp
  resources:
  - podsecuritypolicies
  verbs:
  - use

Configuration scripts can be used to create the required resources

Download the following scripts located at /ibm_cloud_pak/pak_extensions/pre-install directory.

• The pre-install instructions are located at clusterAdministration/createSecurityClusterPrereqs.sh for cluster admins to create the PodSecurityPolicy and ClusterRole for all releases of this chart.

• The namespace scoped instructions are located at namespaceAdministration/createSecurityNamespacePrereqs.sh for team admin/operator to create the RoleBinding for the namespace. This script takes one argument; the name of a pre-existing namespace where the chart will be installed.

  • Example usage: ./createSecurityNamespacePrereqs.sh myNamespace

Configuration scripts can be used to clean up resources created

Download the following scripts located at /ibm_cloud_pak/pak_extensions/post-delete directory.

• The post-delete instructions are located at clusterAdministration/deleteSecurityClusterPrereqs.sh for cluster admins to delete the PodSecurityPolicy and ClusterRole for all releases of this chart.

• The namespace scoped instructions are located at namespaceAdministration/deleteSecurityNamespacePrereqs.sh for team admin/operator to delete the RoleBinding for the namespace. This script takes one argument; the name of the namespace where the chart was installed.

  • Example usage: ./deleteSecurityNamespacePrereqs.sh myNamespace

Installing the Chart

To install the chart with the release name app-nav:

For example:

  helm install --tls ibm-charts/ibm-app-navigator --name app-nav --namespace <namespace>

To specify any extra parameters you can use the --set option or create a yaml file with the parameters and specify it using the -f option on the command line.

Alternatively, you can install the chart from the catalog in the IBM Cloud Private console.

For a complete list of supported parameters, please take a look at the table in the Configuration section below.

It is recommended that the chart only be installed once per cluster.

Verifying the chart

To verify the chart, you need a system with kubectl and helm installed and configured.

1. Check for chart deployment information by issuing the following commands:

   helm list --namespace <namespace>
   helm status --tls app-nav --namespace <namespace>
   

   1. Get the name of the pods that were deployed with ibm-app-navigator by issuing the following command: bash kubectl get pod -n <namespace>

2. For each of the pods, check under Events to see whether images were successfully pulled and that the containers were created and started by issuing the following command with the specific pod name:

   kubectl describe pod <pod name> -n <namespace>
   

   Uninstalling the chart

   1. To uninstall the deployed chart from the IBM Cloud Private console, click Workloads -> Helm Releases.
   • Find the release name and under action click delete.
   1. To uninstall the deployed chart from the command line, issue the following command: bash helm delete --tls --purge app-nav --namespace <namespace>

Configuration

Limitations

See RELEASENOTES.md.

Documentation

Using the IBM Application Navigator