From ee9eb81b629b331c24f105e7d6106eb7acd0b8af Mon Sep 17 00:00:00 2001 From: Curtis Date: Sat, 4 Mar 2023 13:15:44 -0800 Subject: [PATCH] Doc Improvements --- .github/workflows/build-container.yml | 4 +- Dockerfile | 2 +- Makefile | 4 +- deployment/github_app/vars.tf | 2 +- docker-compose-cicd.yaml | 2 +- .../1-install_and_configure.mdx | 2 + docs/web/docs/1-getting_started/2-aws.mdx | 1 - ...er.mdx => 1_install_iambic_via_docker.mdx} | 22 ++++---- ....mdx => 2_install_iambic_via_the_repo.mdx} | 0 .../3_install_iambic_via_python_wheel.mdx | 54 +++++++++++++++++++ .../installation/install_via_the_wheel.mdx | 39 -------------- install.sh | 4 +- 12 files changed, 74 insertions(+), 62 deletions(-) rename docs/web/docs/3-technical_reference/installation/{install_via_docker.mdx => 1_install_iambic_via_docker.mdx} (86%) rename docs/web/docs/3-technical_reference/installation/{download_the_repo.mdx => 2_install_iambic_via_the_repo.mdx} (100%) create mode 100644 docs/web/docs/3-technical_reference/installation/3_install_iambic_via_python_wheel.mdx delete mode 100644 docs/web/docs/3-technical_reference/installation/install_via_the_wheel.mdx diff --git a/.github/workflows/build-container.yml b/.github/workflows/build-container.yml index ef33f695b..5c0708288 100644 --- a/.github/workflows/build-container.yml +++ b/.github/workflows/build-container.yml @@ -57,12 +57,12 @@ jobs: id: build-container run: | docker logout ghcr.io - aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws/o4z3c2v2 + aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws/iambic . build-env/bin/activate && make build_docker make trivy_scan make trivy_sbom make upload_docker - docker logout public.ecr.aws/o4z3c2v2 + docker logout public.ecr.aws/iambic docker buildx prune --filter=until=96h -f - uses: actions/upload-artifact@v3 with: diff --git a/Dockerfile b/Dockerfile index 474954d85..912f54da8 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -FROM public.ecr.aws/o4z3c2v2/iambic_container_base:1.0 +FROM public.ecr.aws/iambic/iambic_container_base:1.0 ARG FUNCTION_DIR="/app" WORKDIR ${FUNCTION_DIR} diff --git a/Makefile b/Makefile index 29d3d43c2..4d938b80c 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ BUILD_VERSION := $(shell python build_utils/tag_and_build_container.py print-current-version) -IAMBIC_PUBLIC_ECR_ALIAS := o4z3c2v2 +IAMBIC_PUBLIC_ECR_ALIAS := iambic .PHONY: prepare_for_dist prepare_for_dist: @@ -7,7 +7,7 @@ prepare_for_dist: .PHONY: auth_to_ecr auth_to_ecr: - bash -c "AWS_PROFILE=iambic_open_source/iambic_image_builder aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws/o4z3c2v2" + bash -c "AWS_PROFILE=iambic_open_source/iambic_image_builder aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws/${IAMBIC_PUBLIC_ECR_ALIAS}" docker_buildx := docker buildx build \ --platform=linux/amd64 \ diff --git a/deployment/github_app/vars.tf b/deployment/github_app/vars.tf index 4eeb976a5..da42331ef 100644 --- a/deployment/github_app/vars.tf +++ b/deployment/github_app/vars.tf @@ -23,7 +23,7 @@ variable "iambic_public_repo_url" { type = string description = "Iambic Public Repo URL" - default = "public.ecr.aws/o4z3c2v2" + default = "public.ecr.aws/iambic" } variable "iambic_image_name" { diff --git a/docker-compose-cicd.yaml b/docker-compose-cicd.yaml index bc015bd68..30b158b46 100644 --- a/docker-compose-cicd.yaml +++ b/docker-compose-cicd.yaml @@ -3,7 +3,7 @@ services: iambic-cicd: # NOTE: This compose file loads the image from ECR, not from what you are running # locally. - image: public.ecr.aws/o4z3c2v2/iambic:latest + image: public.ecr.aws/iambic/iambic:latest environment: - IAMBIC_CONFIG=arn:aws:secretsmanager:us-west-2:759357822767:secret:dev/iambic-full - IAMBIC_CONFIG_ASSUME_ROLE=arn:aws:iam::759357822767:role/IambicSpokeRole diff --git a/docs/web/docs/1-getting_started/1-install_and_configure.mdx b/docs/web/docs/1-getting_started/1-install_and_configure.mdx index bef2b30dd..0e92e7f95 100644 --- a/docs/web/docs/1-getting_started/1-install_and_configure.mdx +++ b/docs/web/docs/1-getting_started/1-install_and_configure.mdx @@ -18,6 +18,8 @@ git init cat < .gitignore **/secrets.yaml proposed_changes.yaml +env/ +venv/ EOF ``` diff --git a/docs/web/docs/1-getting_started/2-aws.mdx b/docs/web/docs/1-getting_started/2-aws.mdx index 426454c7f..5a59a2814 100644 --- a/docs/web/docs/1-getting_started/2-aws.mdx +++ b/docs/web/docs/1-getting_started/2-aws.mdx @@ -49,7 +49,6 @@ After configuring IAMbic, you should see your accounts referenced in your reposi Feel free to move this file around in the repository. When IAMbic is run, it will look for the configuration by referencing the `template_type` and it expects to find a template_type of `NOQ::Core::Config`. - ### 2. Import AWS Resources After configuring IAMbic for AWS, run the `iambic import` command from the repository you created. diff --git a/docs/web/docs/3-technical_reference/installation/install_via_docker.mdx b/docs/web/docs/3-technical_reference/installation/1_install_iambic_via_docker.mdx similarity index 86% rename from docs/web/docs/3-technical_reference/installation/install_via_docker.mdx rename to docs/web/docs/3-technical_reference/installation/1_install_iambic_via_docker.mdx index 3a4c6569b..48bb12104 100644 --- a/docs/web/docs/3-technical_reference/installation/install_via_docker.mdx +++ b/docs/web/docs/3-technical_reference/installation/1_install_iambic_via_docker.mdx @@ -10,11 +10,7 @@ toc_max_heading_level: 5 Before you begin, you'll need to have the following tools installed on your system: -* Docker - -If you don't have these tools installed, follow the instructions below: - -* [Install Docker](https://docs.docker.com/get-docker/) +* Docker ([Install Docker](https://docs.docker.com/get-docker/)) ### Steps @@ -24,38 +20,38 @@ To run the docker container locally, you can use the docker command: Basic run: - docker run public.ecr.aws/s2p9s3r8/iambic:latest + docker run public.ecr.aws/iambic/iambic:latest We recommend mounting a local volume for the templates that are imported: - docker run -it -v :/templates public.ecr.aws/s2p9s3r8/iambic:latest + docker run -it -v :/templates public.ecr.aws/iambic/iambic:latest If you want to run IAMbic from the current directory, you can use a BASH trick to get the current working directory: - docker run -it -v ${pwd}:/templates public.ecr.aws/s2p9s3r8/iambic:latest + docker run -it -v ${pwd}:/templates public.ecr.aws/iambic/iambic:latest It is best to run as the current user to make sure that templates written to disk are written in the user and group currently active on the host: - docker run -it -u $(id -u):$(id -g) -v ${pwd}:/templates public.ecr.aws/s2p9s3r8/iambic:latest + docker run -it -u $(id -u):$(id -g) -v ${pwd}:/templates public.ecr.aws/iambic/iambic:latest Optionally you can store the volume in your system's docker context - be forwarned that the docker context could be coerced to delete the volume without warning using a command like `docker system prune` - it is generally best to store templates on your hard drive in a place where the chances of accidental deletion are minimized: - docker run -it -u $(id -u):$(id -g) -v /templates public.ecr.aws/s2p9s3r8/iambic:latest + docker run -it -u $(id -u):$(id -g) -v /templates public.ecr.aws/iambic/iambic:latest Depending on where your cloud credentials are stored, you may have to mount the relevant directory inside the docker container as well: - docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e "AWS_PROFILE=${AWS_PROFILE}" -v ${pwd}:/templates:Z public.ecr.aws/s2p9s3r8/iambic:latest + docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e "AWS_PROFILE=${AWS_PROFILE}" -v ${pwd}:/templates:Z public.ecr.aws/iambic/iambic:latest ### Shortcut We recommend that you add the following to your ~/.bashrc or ~/.bash_profile: ```bash -echo 'alias iambic="docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e "AWS_PROFILE=${AWS_PROFILE}" -v :/templates:Z public.ecr.aws/s2p9s3r8/iambic:latest "' >> ~/.bashrc +echo 'alias iambic="docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e "AWS_PROFILE=${AWS_PROFILE}" -v :/templates:Z public.ecr.aws/iambic/iambic:latest "' >> ~/.bashrc ``` ```zsh -echo 'alias iambic="docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e "AWS_PROFILE=${AWS_PROFILE}" -v :/templates:Z public.ecr.aws/s2p9s3r8/iambic:latest "' >> ~/.zshrc +echo 'alias iambic="docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e "AWS_PROFILE=${AWS_PROFILE}" -v :/templates:Z public.ecr.aws/iambic/iambic:latest "' >> ~/.zshrc ``` That way you can just execute iambic seamlessly as an application within your system: diff --git a/docs/web/docs/3-technical_reference/installation/download_the_repo.mdx b/docs/web/docs/3-technical_reference/installation/2_install_iambic_via_the_repo.mdx similarity index 100% rename from docs/web/docs/3-technical_reference/installation/download_the_repo.mdx rename to docs/web/docs/3-technical_reference/installation/2_install_iambic_via_the_repo.mdx diff --git a/docs/web/docs/3-technical_reference/installation/3_install_iambic_via_python_wheel.mdx b/docs/web/docs/3-technical_reference/installation/3_install_iambic_via_python_wheel.mdx new file mode 100644 index 000000000..26b198c80 --- /dev/null +++ b/docs/web/docs/3-technical_reference/installation/3_install_iambic_via_python_wheel.mdx @@ -0,0 +1,54 @@ +--- +title: Install IAMbic via Python Wheel +toc_min_heading_level: 2 +toc_max_heading_level: 5 +--- + +## Pre-requisites + +* Python 3.10 or later + +## Install Python if you have not already + +To download IAMbic from PyPI, you will need to ensure that Python is installed on your machine. Here are two methods for installing Python: + +### Method 1: Python + +1. Go to the [Python Downloads page]( https://www.python.org/downloads) and download and install Python 3.10 or later. +1. Create a virtual environment and install IAMbic by running the following commands: + +```bash +# Create a directory for your iambic templates if you didn't already create one +mkdir iambic-templates +cd iambic-templates + +# Create a virtual environment to store iambic and its dependencies +python -m venv venv +. venv/bin/activate + +# Install IAMbic +pip install iambic-core +``` + +Test by running `iambic --help` + +### Method 2: Use pyenv (Recommended for managing multiple versions of Python) + +1. Install [pyenv](https://github.com/pyenv/pyenv) by following the instructions on their GitHub page. (`brew install pyenv` on Mac) +1. Install [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv) by following the instructions on their GitHub page. (`brew install pyenv-virtualenv` on Mac) +1. Create a virtual environment and install IAMbic by running the following commands: + +```bash +# Install the desired version of Python (replace 3.10 with your desired version). +pyenv install 3.10 +# Set the Python version globally with `pyenv global 3.10` or locally within a folder with `pyenv local 3.10`. +pyenv local 3.10 +# Create a virtual environment (replace 3.10 and iambic with your desired version and environment name). +pyenv virtualenv 3.10 iambic +# Activate the virtual environment +pyenv activate iambic +# Install IAMbic +pip install iambic-core +``` + +Test by running `iambic --help` \ No newline at end of file diff --git a/docs/web/docs/3-technical_reference/installation/install_via_the_wheel.mdx b/docs/web/docs/3-technical_reference/installation/install_via_the_wheel.mdx deleted file mode 100644 index de1ec07e8..000000000 --- a/docs/web/docs/3-technical_reference/installation/install_via_the_wheel.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Install via the Python Wheel -toc_min_heading_level: 2 -toc_max_heading_level: 5 ---- - -> Note: the recommended way to run IAMbic is via the [Docker container](./install_via_docker.mdx) - -## Install Python if you have not already - -To download IAMbic from PyPI, you will need to ensure that Python is installed on your machine. Here are two methods for installing Python: - -### Method 1: Download from python.org - -1. Go to the [Python Downloads page]( https://www.python.org/downloads) on the official Python website. -1. Scroll to the "Download Python X.Y.Z" section (where "X.Y.Z" is the latest version number). Note: Noq recommends Python version 3.10 or newer. -1. Select the appropriate download for your operating system. -1. Run the downloaded file and follow the installation instructions. -1. Once the installation is complete, you can use Python in your terminal or command prompt by typing `python` and pressing enter. - -### Method 2: Use pyenv (recommended for managing multiple versions of Python) - -1. Install pyenv by following the instructions on [their GitHub page](https://github.com/pyenv/pyenv). -1. Install the desired version of Python using pyenv. For example, to install Python 3.10, you would run the following command: `pyenv install 3.10`. -1. Once the installation is complete, you can set the Python version globally or locally. Replace `3.10` in these comands with your version of python. -* to set it globally, run the command `pyenv global 3.10` -* if you want to isolate the version of python to a specific folder you can `cd` into that folder and run `pyenv local 3.10`. - -### Method 3: Use a virtual environment to install IAMbic from Pypi -1. Create a virtual environment for the open source project by running the command `pyenv virtualenv `, where is the desired version of Python (e.g. "3.10") and is a name for the virtual environment (e.g. "myenv"). -1. Activate the virtual environment by running `pyenv activate `. You should see the name of the virtual environment in your terminal prompt. -1. Install the open source project using pip by running `pip install `. -1. Once the installation is complete, you can use the package in your Python projects within the virtual environment. - -Note: Some open source projects may have additional requirements or dependencies that must be installed in order to use them. Be sure to read the project documentation or README file for any additional installation instructions. - -## Install IAMbic from Pypi - -To install IAMbic from Pypi, with your Python environment setup, run: `pip install iambic` diff --git a/install.sh b/install.sh index a18bd52f3..2d0652540 100755 --- a/install.sh +++ b/install.sh @@ -34,7 +34,7 @@ fi echo -ECR_PATH="public.ecr.aws/o4z3c2v2/iambic:latest" +ECR_PATH="public.ecr.aws/iambic/iambic:latest" echo "Installing iambic..." DOCKER_CMD="#!/bin/bash @@ -53,7 +53,7 @@ done ENV_VAR_ARGS=\"\$ENV_VAR_ARGS -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials\" ENV_VAR_ARGS=\"\$ENV_VAR_ARGS -e AWS_CONFIG_FILE=/app/.aws/config\" -docker run -w /templates -it -u \$(id -u):\$(id -g) -v \${HOME}/.aws:/app/.aws \$ENV_VAR_ARGS --mount \"type=bind,src=\$(pwd),dst=/templates\" public.ecr.aws/o4z3c2v2/iambic:latest \"\$@\"" +docker run -w /templates -it -u \$(id -u):\$(id -g) -v \${HOME}/.aws:/app/.aws \$ENV_VAR_ARGS --mount \"type=bind,src=\$(pwd),dst=/templates\" public.ecr.aws/iambic/iambic:latest \"\$@\"" echo