End-to-end UX of deploying Conjur OSS with the helm chart and running apps in K8s is reviewed

[izgeri]

More details TBA

We would like to perform XA using the draft updated documentation (link TBA) for Kubernetes authentication to run through the end-to-end experience of using Conjur OSS with Kubernetes-deployed applications.

[diverdane]

I created some applications on a GKE cluster using a modified version of the conjurdemos/kubernetes-conjur-demo scripts, and reviewed the Conjur documentation re. authn-k8s.

Summary / Key Takeaways

• Documentation is in good shape, only a couple of changes suggested.
• However, documentation is scattered. So someone playing the roles of both security admin and app developer will need to jump between Conjur documentation (e.g. for enabling authn-k8s and configuring policies) and documentation for setting up applications e.g. for setting up a Secretless broker sidecar or for setting up Summon. So it's important to have some good demos/examples for how to configure all-the-things on an existing Conjur-OSS deployment.
• Biggest potential pitfall: See Item #1 in Findings/Action Items section below. Best solution is to integrate the creation of a Conjur account into the Conjur OSS helm chart, maybe as a post-install Helm hook.
• Another big pain point is that we need a good troubleshooting guide for Conjur authn-k8s. There's an existing issue filed: https://app.zenhub.com/workspaces/community-and-integrations-team-5e28ab8f700a191286d5abe0/issues/cyberark/conjur-docs/958

Findings/Action Items

1. Conjur OSS Helm Chart Documentation: Chart Value account MUST match Conjur Account That you Expect to Create

   This needs to be documented!!! Let's say you deploy a Conjur OSS server, using either an explicit setting for chart value account or using the default value of "default"). If you later create a Conjur account on this server, then you will need to either:

   • Use the same value for Conjur account as you used for the chart value account, or...
   • Do a Helm upgrade after you've created a Conjur account to update the chart value account to match the Conjur account value.

   Failing to do this will cause Kubernetes authn-k8s authentication to fail.

   Perhaps a better alternative would be to add an option to have the Conjur OSS Helm chart to create an account as a post-install hook.

2. Conjur Documentation Should Use "identity" Instead of "host" in Some Places

   For example, in https://docs.conjur.org/latest/en/Content/Integrations/Kubernetes_AppIdentity.htm?tocpath=Integrations%7COpenShift%252C%20Kubernetes%7C_____2#ApplicationIdentityinOpenShiftKubernetes

   • This line: The following are the Kubernetes resources that you can define as hosts: should be: The following are the Kubernetes resources that you can define as authentication identities:

     • This line: We recommend using this option as a transition, and move towards using the Kubernetes Deployment and StatefulSet resources as hosts. Should be: We recommend using this option as a transition, and move towards using the Kubernetes Deployment and StatefulSet resources as authentication identities.

     • This line: Define Kubernetes Resources as Conjur hosts Should be: Define Kubernetes Resources as Conjur Identities

3. Inconsistent use of ClusterRole vs Role I believe Role (which is namespace scoped) is preferred?

   • Role used in docs.conjur.org: https://docs.conjur.org/latest/en/Content/Get%20Started/scl_using-conjur-OSS.htm#conjur-authenticator-role.yml
   • ClusterRole used in docs.cyberark.com: https://docs.cyberark.com/Product-Doc/OnlineHelp/AAM-DAP/Latest/en/Content/Integrations/Kubernetes_deploySecretlessSidecar.htm#grant-the-dap-follower-access-to-pods-in-the-namespace

4. Secretless Getting Started Doc uses Old Style /service_account/ as host

   Should be change to be consistent with other examples that use the application name as host?

   A service account host is defined here: https://docs.secretless.io/Latest/en/Content/Get%20Started/using-dap.htm#EnabletheKubernetesauthenticatorforyourapplication

    - !host
    id: APP_NAMESPACE/service_account/APP_SERVICE_ACCOUNT
    annotations:
      kubernetes/authentication-container-name: secretless
      kubernetes: "true"
    # grant membership to the conjur/authn-k8s/AUTHENTICATOR_NAME/apps layer
   - !grant
    role: !layer
    member: !host APP_NAMESPACE/service_account/APP_SERVICE_ACCOUNT

   The corresponding CONJUR_AUTHN_LOGIN is defined here: https://docs.secretless.io/Latest/en/Content/Get%20Started/using-dap.htm#AddSecretlesstoyourappdeploymentmanifest

           - name: CONJUR_AUTHN_LOGIN
     value: "host/conjur/authn-k8s/AUTHENTICATOR_NAME/apps/APP_NAMESPACE/service_account/APP_SERVICE_ACCOUNT"

5. Conjur OSS Helm Chart Documentation Should Provide Examples Showing authn-k8s Authentication

   • We can point to conjurdemos/kubernetes-conjur-demo scripts.
   • I have some changes to this repo which should allow the scripts to run directly on a Conjur-OSS cluster that has been deployed via Conjur OSS Helm chart.

6. Conjur OSS Helm Chart Documentation Needs to Show How to Enable Debug Mode

7. Trouble Shooting Wiki Needs to Include a Step-by-Step Guide to Debugging authn-k8s There is an issue filed already: https://app.zenhub.com/workspaces/community-and-integrations-team-5e28ab8f700a191286d5abe0/issues/cyberark/conjur-docs/958

[izgeri]

8. There is a blog post that walks through the e2e experience of deploying & configuring Conjur OSS and deploying apps to Kubernetes

[izgeri]

@diverdane were follow-up issues filed for all of these items and put in the epic #74? If that's the case, then I think this issue can be closed now