OSDOCS-11830 Split Networking content for ROSA with HCP

[laubai]

Version(s): 4.17+

Issue:
https://issues.redhat.com/browse/OSDOCS-11830

Link to docs preview:

• About networking
• Networking operators
  • AWS Load Balancer Operator
  • DNS Operator
  • Ingress Operator
  • Ingress Node Firewall Operator
• Network verification
• Configuring a cluster-wide proxy during installation
• CIDR range definitions
• Network security
• Configuring the primary cluster network
• Configuring routes

QE review:

• QE has approved this change.

[openshift-ci]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[laubai]

/test all

[ocpdocs-previewbot]

🤖 Tue Jun 03 09:22:55 - Prow CI generated the docs preview:
https://88279--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

[laubai]

/test all

[ocpdocs-vale-bot]

🤖 [error] OpenShiftAsciiDoc.XrefContainsAnchorID: The xref is missing an anchor ID.

[laubai]

/test all

[laubai]

/test all

[laubai]

/test all

[laubai]

/test all

[laubai]

/test all

[laubai]

/test all

[laubai]

/test all

[laubai]

/test all

[andyrepton]

This command fails with the above Variable:

An error occurred (InvalidID) when calling the CreateTags operation: The ID 'subnet-09731120e976e8580 subnet-0c18738ade8ebe7e7 subnet-06b27cfc96002f754' is not valid

This will only happen for customers using Z shell (zsh) instead of Bourne Again Shell (bash), but zsh is the default for any Macbook user which could cause some confusion for a lot of people following this guide. Unfortunately, there's not a clean answer for this. We have three options:

1. Make a big highlight warning saying that the user must use the bash shell
2. Turn this section into a little bash script that we ask the customer to create and then run rather than putting the commands into the shell directly (I think this is the simplest)
3. Rewrite the commands to try and be shell agnostic (this is also tricky)

If we go with option 2, then we'd change this section to be:

Create a small script to tag your subnets:

cat <<EOF > "${SCRATCH}/tag-subnets.sh"
#!/bin/bash

aws ec2 create-tags \
     --resources ${PUBLIC_SUBNET_IDS} \
     --tags Key=kubernetes.io/role/elb,Value='' \
     --region ${REGION}

aws ec2 create-tags \
     --resources ${PRIVATE_SUBNET_IDS} \
     --tags Key=kubernetes.io/role/internal-elb,Value='' \
     --region ${REGION}

EOF

Execute the script. The reason for this step is due to differences in bash versus zsh

bash ${SCRATCH}/tag-subnets.sh

[laubai]

Agree option 2 makes sense here but I think for the most part we do assume a Bash shell for better and worse; will check with the rest of the openshift team re. execution environment.

Alternatively, could we recommend something generic like "If you use a zsh terminal instead of a bash terminal, prefix all commands in this doc with bash to ensure the appropriate environment is used"?

[andyrepton]

If we go with the script option above then this bit can go too

[andyrepton]

I recommend putting back the check on the POLICY_ARN to see if it exists first. If the policy already exists, the new command will fail and subsequent commands will then fail. This will work:

OPERATOR_POLICY_ARN =$(aws iam list-policies --query \
      "Policies[?PolicyName=='aws-load-balancer-operator-policy'].{ARN:Arn}" \
      --output text)

if [[ -z "${OPERATOR_POLICY_ARN}" ]]; then
  OPERATOR_POLICY_ARN =$(aws  iam create-policy \
  --query Policy.Arn --output text \
  --policy-name aws-load-balancer-operator-policy \
  --policy-document file://${SCRATCH}/operator-permission-policy.json \
  --region ${REGION})
fi

echo $OPERATOR_POLICY_ARN

[laubai]

I removed this initially because the output didn't ever seem to let the create-policy command succeed, and it didn't tell you anything about a failure - whereas if you just run the create-policy command and it fails, it at least provides you with an error message that you can use for further troubleshooting.

@andyrepton Would it make sense to check for an existing policy up front and tell the user to edit an existing policy if it exists? e.g. "NOTE: If the policy already exists, review and edit the existing policy to include the appropriate permissions. For more information, see Edit IAM policies in the AWS documentation.

[andyrepton]

This is why we have the echo there at the end, if the command fails then it'll return something other than the ARN. Would it be ok to add a note saying to confirm the ARN looks correct before proceeding?

[andyrepton]

I recommend explicitly setting the OPERATOR_ROLE_ARN here, either via something like this:

Export the OPERATOR_ROLE_ARN variable:

export OPERATOR_ROLE_ARN=$your_role_arn

Or in the create role command like was originally there:

OPERATOR_ROLE_ARN=$(aws iam create-role --role-name "${CLUSTER_NAME}-alb-operator" \
  --assume-role-policy-document "file://${SCRATCH}/operator-trust-policy.json" \
  --query Role.Arn --output text)

echo ${OPERATOR_ROLE_ARN}

Otherwise the user may proceed to installing the operator later without ever checking that this variable was set and being confused as to why it isn't working

[andyrepton]

Recommend changing to ${REGION} to be consistent with the rest of the document

[andyrepton]

This is missing a /, which causes it to fail. I also recommend the same as above, and setting the CONTROLLER_POLICY_ARN to be the output of the command. Suggested edit:

CONTROLLER_POLICY_ARN=$(aws iam list-policies --query \
      "Policies[?PolicyName=='aws-load-balancer-controller-policy'].{ARN:Arn}" \
      --output text)

if [[ -z "${CONTROLLER_POLICY_ARN}" ]]; then
  CONTROLLER_POLICY_ARN=$(aws  iam create-policy \
  --query Policy.Arn --output text \
  --policy-name aws-load-balancer-controller-policy \
  --policy-document file://${SCRATCH}/controller-permission-policy.json \
  --region ${REGION})
fi

echo ${CONTROLLER_POLICY_ARN}

[laubai]

I suspect this depends on whether you've set a fully qualified path for ${SCRATCH} or not, will see if I or another writer can re-test

[EDIT] Oh wait you mean after the SCRATCH env var not before it - on it!

[andyrepton]

Same as above, missing the / on the document file. Suggested change to be consistent with above:

CONTROLLER_ROLE_ARN=$(aws iam create-role --role-name "${CLUSTER_NAME}-albo-controller" \
  --assume-role-policy-document "file://${SCRATCH}/controller-trust-policy.json" \
  --query Role.Arn --output text)

echo ${CONTROLLER_ROLE_ARN}

[andyrepton]

OIDC_ARN has not been set in this document. To keep consistency set it the same way as above. Correct line:

"Federated": "arn:aws:iam::${AWS_ACCOUNT_ID}:oidc-provider/${OIDC_ENDPOINT}"

[openshift-ci]

@laubai: all tests passed!

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[hunterkepley]

Besides the standing comments, I don't see anything I would change