From ee90280c8619a8296d68ca15bac5b5560e485bee Mon Sep 17 00:00:00 2001 From: Esteban Rey Date: Fri, 30 Jul 2021 19:21:24 -0700 Subject: [PATCH] Add informational teleport docs on current teleport repository management (#564) * Create repository flow expectation * Updated faq and added more information * add convenicence script for enabling teleport * add constraint info to readme * small error * Remove unnecessary/incomplete detail --- docs/teleport/README.md | 1 + .../find-teleport-enabled-repositories.sh | 39 ++++ .../teleport-repository-management.md | 204 ++++++++++++++++++ 3 files changed, 244 insertions(+) create mode 100644 docs/teleport/find-teleport-enabled-repositories.sh create mode 100644 docs/teleport/teleport-repository-management.md diff --git a/docs/teleport/README.md b/docs/teleport/README.md index ada4827..e30d394 100644 --- a/docs/teleport/README.md +++ b/docs/teleport/README.md @@ -36,6 +36,7 @@ Additional services and scenarios will come online as we incorporate more feedba Preview 2 has the following constraints. Your feedback will help us prioritize this list. +- 10 Repository limit. More info: [teleport-repository-management](./teleport-repository-management.md) - Limited to running images with [AKS][aks-getting-started] - Support for [premium registries][acr-tiers] - Registries must exist in the following regions: diff --git a/docs/teleport/find-teleport-enabled-repositories.sh b/docs/teleport/find-teleport-enabled-repositories.sh new file mode 100644 index 0000000..ca9a668 --- /dev/null +++ b/docs/teleport/find-teleport-enabled-repositories.sh @@ -0,0 +1,39 @@ +#!/bin/bash +# Prerequisites: +# azure cli (logged in) +# jq +# usage: find-teleport-enabled-repositories.sh acr-name + +ACR_NAME=$1 + +enabled_repos=() + +IFS=$'\n' # Each iteration of the for loop should read until we find an end-of-line +for row in $(az acr repository list --name ${ACR_NAME} | jq '.[]' | jq @sh) +do + # Run the row through the shell interpreter to remove enclosing double-quotes + stripped=$(echo $row | xargs echo) + stripped=$(echo $stripped | xargs echo) + + is_teleport_enabled=$(az acr repository show --name "${ACR_NAME}" --repository "${stripped}" --query "changeableAttributes.teleportEnabled") + + if [[ "$is_teleport_enabled" = 'true' ]]; then + echo "$stripped -> Enabled" + enabled_repos+=("$stripped") + else + echo "$stripped -> Disabled" + fi + +done + +unset IFS + +echo "" +echo "Summary:" +echo "Enabled Repositories:" +echo "" + +for value in "${enabled_repos[@]}" +do + echo $value +done \ No newline at end of file diff --git a/docs/teleport/teleport-repository-management.md b/docs/teleport/teleport-repository-management.md new file mode 100644 index 0000000..315e220 --- /dev/null +++ b/docs/teleport/teleport-repository-management.md @@ -0,0 +1,204 @@ +# Manage Repositories in Teleport Enabled Registries + +## Existing Limitations +- Registries must first be Teleport enabled to enable repositories +- There is a current 10 teleport enabled repository limit for registries + +## Existing Flow + +At the moment if a repository is teleport enabled, this means it can expand images that are pushed into it making them into the teleport format. Note that this does not interfere with regular registry storage and teleportable (expanded) layers are stored in a separate storage than typical layers. Making a repository enabled does not however expand all existing images in it, rather all images pushed after the fact will be expanded. + +This can be best illustrated with examples, take a new empty registry that has already been teleport enabled, in this case we can summarize its state as: + + Registry A + Properties + - Teleport enabled + -> Repositories + (none) + + +Pushing any image to Registry A will result in the creation of a teleport enabled repository, for visualization: + + Push ubuntu:18.0.1 to Registry A + + Registry A + Properties + - Teleport enabled + -> Repositories + ubuntu (Teleport Enabled) + |-> Tag: 18.0.1 + Can be pulled from teleport client + + +Now consider a non empty registry, registry B that has just had teleport enabled + + Registry B + Properties + - Teleport enabled + -> Repositories + python (Not Teleport Enabled) + |-> Tag: latest + Cannot be pulled from teleport client + +Pushing a new image not already present will result in: + + Push ubuntu:18.0.1 to Registry B + + Registry B + Properties + - Teleport enabled + -> Repositories + python (Not Teleport Enabled) + |-> Tag: latest + Cannot be pulled from teleport client + + ubuntu (Teleport Enabled) + |-> Tag: 18.0.1 + Can be pulled from teleport client + +If we want to enable python we can similarly re push the python image resulting in: + + Push python:latest to Registry B + + Registry B + Properties + - Teleport enabled + -> Repositories + python (Teleport Enabled) + |-> Tag: latest + Can be pulled from teleport client + + ubuntu (Teleport Enabled) + |-> Tag: 18.0.1 + Can be pulled from teleport client + +A tricky thing however is that if instead of the last step we pushed a different image for repository python (where latest and 2.2 dont share a digest) we would see this state: + + + Push python:2.2 to Registry B + + Registry B + Properties + - Teleport enabled + -> Repositories + python (Teleport Enabled) + |-> Tag: latest + Cannot be pulled from teleport client + Tag: 2.2 + Can be pulled from teleport client + + ubuntu (Teleport Enabled) + |-> Tag: 18.0.1 + Can be pulled from teleport client + + +## Manually Select which Repositories Are Teleport Enabled + +The previous operation does not give customers much control over which registries are teleport enabled as a result we do have an existing flow to chose which repositories are enabled and which arent, note however that as long as a repository is under the 10 repo limit all pushes to non teleport enabled repositories (new or otherwise) will become teleport enabled (even if the flag here was set manually to disabled) + +The previous step should have provided some insights as to how we currently enable teleport on a repository. Here is how to explicitely set and check which repositories are teleport enabled. + +### Identify which repositories are teleport enabled + +To currently identify if a speific repository is teleport enabled we can run the following command and looking at the teleport enabled field: + +```bash +az acr repository show --repository -o jsonc +{ +"changeableAttributes": { + "deleteEnabled": true, + "listEnabled": true, + "readEnabled": true, + "teleportEnabled": true, + "writeEnabled": true + } +} +``` + +We have also provided a convenicence script to find this out for all repositories in a registry in case there are a lot and determining this becomes difficult. P.S this is not super fast but saves manually checking one by one. + +> Note: Assure [find-teleport-enabled-repositories.sh](./find-teleport-enabled-repositories.sh) is set to execute: `sudo chmod +x find-teleport-enabled-repositories.sh` + +You can run this as follows: + +```bash +./find-teleport-enabled-repositories.sh registry-name +``` + +Sample output: +```bash +/find-teleport-enabled-repositories.sh teleporttest +gcc -> Enabled +glassfish -> Enabled +jupyter/all-spark-notebook -> Enabled +python -> Disabled +rethinkdb -> Enabled + +Summary: +Enabled Repositories: + +gcc +glassfish +jupyter/all-spark-notebook +rethinkdb + +``` + + + + +### Manually disable teleport on a repository + +For the time being we disable teleport on a repository using the [edit-teleport-attribute.sh](./edit-teleport-attribute.sh) included in this repo. This can be used by first setting env variables for credentials: + +> Note: Assure [edit-teleport-attribute.sh](./edit-teleport-attribute.sh) is set to execute: `sudo chmod +x edit-teleport-attribute.sh` + +```bash +export ACR_USER=teleport-token +export ACR_PWD=$(az acr token create \ + --name teleport-token \ + --registry $ACR \ + --scope-map _repositories_pull \ + --query credentials.passwords[0].value -o tsv) + +edit-teleport-attribute.sh disable --debug +``` + +### Manually enable teleport on a repository + +Once the registry has less than 10 teleportable repositories enabled, the next repository for which an image is pushed that is not already teleport enabled will become teleport enabled. As a result there is no direct need of enabling teleport for it, instead you can just push an image to said repository. + +Nonetheless for completeness [edit-teleport-attribute.sh](./edit-teleport-attribute.sh) script can set this metadata field to enable teleport on a repository manually (you will still need to push afterwards so the image will expand in the background). + +```bash +export ACR_USER=teleport-token +export ACR_PWD=$(az acr token create \ + --name teleport-token \ + --registry $ACR \ + --scope-map _repositories_pull \ + --query credentials.passwords[0].value -o tsv) + +edit-teleport-attribute.sh enable --debug +``` + +After, new images pushed to the enabled repository will be expanded and teleportable. + +## FAQ + + - Can the Teleport 10 repository limit be raised? + + ``` The 10 repository limit is a temporary measure during the private preview phase. We do not currently have a way to raise this value for a particular registry. If necessary users can request a second registry to be teleport enabled ``` + + - Will pushing one image to an existing repository (making it teleport enabled) expand all existing tags making them teleportable? + + ``` Unfortnately we do not currently support backfill so only layers contained in pushes after teleport has been enabled on the registry will be fixed ``` + + - Is there a timeline to improve this behaviour? + + ``` We have a plan to improve this behaviour but the exact timeline is not set in stone ``` + + - How can I tel if an image in a teleport enabled repository is actually teleportable? + + ``` This can be done using the check-expansion script also provided in this registry ``` + +