search

cyberark / katacoda-scenarios

CyberArk Katacoda Scenarios
MIT License
1 stars 1 forks source link

Add Java-Client-API to Katacoda Scenario #5

Closed mdodell closed 4 years ago

mdodell commented 4 years ago

A link to this Katacoda Scenario can be found here: Java-Client-API Scenario

izgeri commented 4 years ago

@mdodell I had some thoughts after seeing you demo this scenario. I’m not sure yet which things we should try to fix before the PR is merged and which we should do as follow-ons, but if any of these are simple enough to start with I’d suggest making these changes as separate commits from what you have so far.

  1. I don’t think we should include the alternate “run one script and all the magic happens” flow. It doesn’t add anything to the demo and it’s kind of confusing.
  2. Maybe even more important, do you feel clear about the 4 steps of the demo? This is a different format than the original demo, so how did it translate? In this format, we’re trying to teach someone something - do our 4 steps of the demo accomplish that? If not, how would you change them?
  3. Is there a way to cut down on the amount of time the tutorial takes (besides having custom base images, which we don’t have right now)? 20 minutes is a long time for a tutorial flow. Maybe after Bradley’s work is in Step 1 (building the client) can be totally dropped?
  4. Are there sane defaults we can set for things so that fewer steps are required but the demo is still clear? For example, we set the authenticator ID as an env var and then interpolate it into a policy. But maybe it'd be clearer just to hardcode it and show / explain the policy that includes it?

I might have other ideas as well, but I think now that you've migrated the content and gotten it working end-to-end, the next step is to look at it with a critical eye and ask:

You can use that you are newer to Conjur development to your advantage - are any of the steps unclear to you? Then we should probably dig into that and improve the step / enhance the explanation. The team is ready to help with whatever questions you have :)

izgeri commented 4 years ago

some notes from running through it just now:

page 1

page 2

page 3

page 4

I put a lot of feedback in the list above, but basically it still reads as not very clear about what the purpose of the tutorial is and how the steps along the way are helping me to achieve that purpose. mostly right now it feels like running a bunch of steps, and I'm not sure why or what I'm doing.

in this tutorial, you are teaching!! so start out by describing what's in this lesson, the steps that you'll take to get there, and then make sure that each page of the tutorial is walking through one of those steps

I don't think it would be bad to have a main page that just sets the context and runs no commands

I would suggest that the flow look something like this: page 1: describe the purpose of the tutorial and what steps you'll be working through (maybe run minikube start at the very beginning because it takes a minute and why not) page 2: build a docker image for a simple java app (that does what?) that will use our conjur java client to connect with conjur given an access token provided by our kubernetes authenticator client sidecar page 3: deploy conjur using our helm chart, which deploys (list of stuff). configure conjur to enable the kubernetes authenticator page 4: configure conjur to enable the app: load policy to grant the app a host identity, add secrets the app will need, add entitlements to grant the app access to the secrets page 5: deploy the application with the conjur authenticator client sidecar and verify it can retrieve secrets from conjur as expected

mdodell commented 4 years ago

some notes from running through it just now:

page 1

  • [x] I don't think we call it the "java client API" anywhere, and the wording sounds odd to me. can we call it the "java API" or (better) the "java client library"? it's really the java client library for the conjur API. sometimes we call it the "java SDK", but that's not quite right either.
  • [x] is it typical that you have to wait for the katacoda tutorial to load in the files? that seems odd. are our files particularly big or something?
  • [x] can we rename java-client-api to conjur-java-client?
  • [x] for the java build (which we eventually want to remove, right?) can we run pushd conjur-java-client and then end on popd so the next page starts from the right directory?

page 2

  • [x] can we remove the PROJECT_NAME env var entirely and just use the hardcoded demo-java-client (or maybe even rename to java-demo?) wherever it was?
  • [ ] can we add some more context about what the data key does in the "create a data key" step?
  • [x] why does the numbering on this page restart at (1)?

Fixed, Katacoda just hadn't repopulated the new code yet.

  • [ ] in the helm install step, are there custom values set in the custom-values.yaml? could we look at those and explain them? can we explain in this step what the helm chart is deploying?
  • [ ] we can't run the "Create a Conjur account and generate an API Key" step until the conjur pods are up. how do they handle this in the quick start? can a similar approach be used here?

See the comment about the wait-for-pod.sh sugestion.

  • [ ] in "create a conjur CLI pod" why are we doing that? what's the benefit of the CLI pod?
  • [ ] in the last step, "check pod status", what am I looking for? maybe this is covered by "expected output", but I think it'd be good to add some info about why this step is part of the tutorial

wait-for-pod.sh suggestion: The build script had a loop that checked the pod status every two seconds, and ran for a total of 100 seconds. If all of the pods were running, it would break from the loop. Since we are working outside of a script, I thought that running kubectl get pods would be satisfactory. Another option is to have the user run a short script, something along the lines of wait-for-pod.sh --pod-name <pod-name> --num-of-contains <number-container> that the user executes, and it prints out a message every iteration of the loop saying: Waiting for the pod to be up... Waiting for the pod to be up... Waiting for the ____ pod to be up... Pod is up!

page 3

  • [ ] in step (2) the conjur init command has the ability to accept flags - would using flags make this command clearer? it's pretty fuzzy right now
  • [ ] we should try to clean up the errors / warnings around Unable to use a TTY - input is not a terminal or the right kind of file and stty: 'standard input': Inappropriate ioctl for device

This happens in the quick start tutorial too. I think it's because of how the structure of that command is built. If you have the user say simply conjur init, then they can type in yes, $ACCOUNT_NAME, and y themselves.

  • [ ] rather than saving the username admin in the "authninputfile you could just pass-u adminon theconjur authn login` request (which is a more standard flow anyway)
  • [ ] loading the policies is like black magic right now - I don't know what the policies say or why I'm loading them
  • [ ] why do we have two separate certificate configmaps?

page 4

  • [ ] what is the java client docker image? maybe this should be explained on page 1
  • [ ] any manipulation of the docker image should happen at the same time as its created (eg tagging) - on this last page, I think what we're trying to do is deploy the app and verify it works, and that should be the focus
  • [ ] I couldn't finish because the init container didn't come up, so I ended on the second to last step 😢

I put a lot of feedback in the list above, but basically it still reads as not very clear about what the purpose of the tutorial is and how the steps along the way are helping me to achieve that purpose. mostly right now it feels like running a bunch of steps, and I'm not sure why or what I'm doing.

in this tutorial, you are teaching!! so start out by describing what's in this lesson, the steps that you'll take to get there, and then make sure that each page of the tutorial is walking through one of those steps

I don't think it would be bad to have a main page that just sets the context and runs no commands

I would suggest that the flow look something like this: page 1: describe the purpose of the tutorial and what steps you'll be working through (maybe run minikube start at the very beginning because it takes a minute and why not)

Should page 1 be considered a step? There is an intro.md file, that describes the purpose of the tutorial to some extent, but I can write some clarifications there. That intro file can also be removed so the user is immediately prompted into step 1.

The minikube start command can also be immediately loaded in so the user does not even have to run the command. It will still take a minute for it to finish, but at least they do not have to be concerned with executing the command itself.

page 2: build a docker image for a simple java app (that does what?) that will use our conjur java client to connect with conjur given an access token provided by our kubernetes authenticator client sidecar page 3: deploy conjur using our helm chart, which deploys (list of stuff). configure conjur to enable the kubernetes authenticator page 4: configure conjur to enable the app: load policy to grant the app a host identity, add secrets the app will need, add entitlements to grant the app access to the secrets page 5: deploy the application with the conjur authenticator client sidecar and verify it can retrieve secrets from conjur as expected

izgeri commented 4 years ago

Thanks - I'm seeing now that my big batch of comments is hard to go back and forth on :) I'll spend some time tomorrow to migrate outstanding ones to line-level comments to make the back-and-forth easier. We may also want to hop on a short call tomorrow, because my sense is that some of the context of my questions is lost in the deluge. I'll get in touch to set that up early tomorrow!

mdodell commented 4 years ago

@izgeri Follow-up from today's' conversation:

All other improvements have been marked on your original comment.

Clarifications/help needed

  1. When we are waiting for pods to be online, should we create a script that prints messages that say "loading..." in the shell? I improved the description of those pods to say: "Wait for the ____ pods to run" by running the command kubectl get pods
  2. For your suggestion regarding authn login under page 3, I'm having a lot of difficulty trying to implement them.

For instance, for the authn login command, here is the output when I try either copying and pasting or even manually writing the API key (the password) in:

$ kubectl exec -it "$CONJUR_CLI_POD" conjur authn login -- -u admin
Please enter admin's password (it will not be echoed):
Unable to authenticate with Conjur. Please check your credentials.
command terminated with exit code 1

I looked in the documentation, and didn't see a flag for password. I even tried passing in $API_KEY, which is the environment variable for the API key.

Any advice? I feel like having a password flag there would be super helpful if it doesn't exist!

izgeri commented 4 years ago

we've done a lot of back and forth work on this tutorial, and much thanks to @mdodell for sticking with me on it. it looks like it's going to be hard to trim it down to a reasonable size, so we're going to need to rethink the tutorial we want to write and close this PR for now

thanks again to @mdodell for working so hard on this!!