Documentation issues

[orefalo]

Alright, I am trying to install this piece of software, which honestly seems to be 'on spot' for the features I am looking for. Now it's far from trivial - the ouctl utility was build to mitigate the core issue: the documentation is VERY poor quality.

I will be using this issue to propose improvements and track my struggles,

Let's start with what would be a better TOC

Introduction
Deploying OpenUnisson <- the page talks about deploying the login portal, it's confusing. We want to deploy Unisson, not a subcomponent.
Core Features/
    Kubectl Plugin
    Multicluster sso
    Namespace as a Service
Applications/  <- rename to **Integrations**
   Github
   Kiali
   K8s integration
   Identity Providers/ <- Actually, I would move the contents to the Integrations folder for clarity. In the end you have identity integrations, some with extended features.
      ....
Customization/
   ...
Knowledgebase/
    Ingresses/...
    ...
Documentation/ <- Maybe a better name? or maybe move the pages around.
  Operator Helm Chart Customization <- this page is empty

Upgrading to 1.0.23...  <- put this last in the TOC, it doesn't belong close to the intro
Getting Help

[orefalo]

Next, missing from the docs and the default values.yaml:

dashboard:
    # enables the k8s dashboard in the portal
    enabled: false

[orefalo]

It also appears as if traefik is a supported ingress. I can see the orchestra yaml, am I missing something?

FYI, traefik is the default ingres in rancher k3s and many other low resources distributions

[mlbiam]

the ouctl utility was build to mitigate the core issue: the documentation is VERY poor quality.

I appreciate the feedback and am certainly going to update the docs and structure. I'm going to push back here though. First, the ouctl command wasn't built to mitigate poor quality documentation. OpenUnison provides a very wide breadth of features and is used to manage access to a wide range of clusters from various cloud providers. In addition to providing authentication for clusters, it adds automated provisioning, multi cluster sso, multi site integration, etc. Most of our commercial customers add additional Application and Workflow objects to further customize their deployments. The ouctl command was created to simplify those rollouts at scale (I think our largest customer has >100 clusters world wide). Helm does not include much in the way of management functions, chart retries, sequence management, etc where as ouctl does provide these functions.

As for the documentation quality, I also need to push back a bit. The OpenUnison helm charts don't just deploy OpenUnison, but also deploys Ingress objects, helps with certificate management (and with Namespace as a Service may be used to deploy ActiveMQ) and has to account for a wide range of users from "I just started Kubernetes" to "I've been using Kubernetes for 5+ years". Our documentation also encompasses multiple integration points, including Ingress controllers and identity providers. It's very difficult to provide concise documentation from all those angles and is far beyond what most other identity projects provide.

Again, I very much appreciate your feedback and it will be incorporated. Please take into account the number of perspectives we're writing to before making judgements.

[mlbiam]

It also appears as if traefik is a supported ingress.

We do, but we need to document it. It was originally added https://github.com/TremoloSecurity/OpenUnison/issues/617#issuecomment-1046983419 and we were going to get more feedback on the instructions which never came. That's on us for not then consolidating into our docs.

FYI, traefik is the default ingres in rancher k3s and many other low resources distributions

Thanks for the info, I don't run into it much. Most of our customers are enterprises and are using Istio or NGINX. Thanks for the info!

[orefalo]

I agree, helm is not a good fit for these large deployments. I use helmsman for similar benefits, albeit not as user-friendly.

Far from me the intent to make bad judgements, rather I try to make things better and easier for others. In this context, what better starting point than a friendly user that provides feedback about his struggles?

Should you have the doc under source control, I will be happy to help out.

If I may add another area of improvement in the document, I found that adding an application to the portal is not clearly documented. I found this closed ticket yesterday - https://github.com/OpenUnison/openunison-k8s/issues/32. It came as a surprise that new portal applications were actually managed via the operator. I may have missed it.

Sincerely,

PS: I am still stuck on my install - but it's not documentation related, will open a ticket