diff --git a/.vale/styles/spelling-exceptions.txt b/.vale/styles/spelling-exceptions.txt index bd66d15f1f..971fe34ef9 100644 --- a/.vale/styles/spelling-exceptions.txt +++ b/.vale/styles/spelling-exceptions.txt @@ -242,3 +242,4 @@ Yaml YAML yamllint YouTube +AIOps \ No newline at end of file diff --git a/docs/docs/development/frontend/getting-set-up.mdx b/docs/docs/development/frontend/getting-set-up.mdx index dbc29ca1cd..faa2c2deb9 100644 --- a/docs/docs/development/frontend/getting-set-up.mdx +++ b/docs/docs/development/frontend/getting-set-up.mdx @@ -34,7 +34,7 @@ npm install npm start ``` -You can access your local server at [http://localhost:8080/](http://localhost:8080/). If you are not familiar with Infrahub, follow our [Getting Started Guide](../../getting-started/overview.mdx). +You can access your local server at [http://localhost:8080/](http://localhost:8080/). If you are not familiar with Infrahub, follow our [Overview Guide](../../overview/overview.mdx). ## 3. Run all tests diff --git a/docs/docs/faq/faq.mdx b/docs/docs/faq/faq.mdx index d179d99408..93b3314d16 100644 --- a/docs/docs/faq/faq.mdx +++ b/docs/docs/faq/faq.mdx @@ -26,7 +26,7 @@ Infrahub is an open-source platform that enables infrastructure as code by provi - Integrations: Integrations with tools like NetBox, Nautobot, Ansible, and Nornir. Ability to build custom integrations. - Python SDK: Programmatically interact with Infrahub using a Python SDK. -For more information, see our [Infrahub overview](../getting-started/overview.mdx). +For more information, see our [Infrahub overview](../overview/overview.mdx). ### I'm just getting started with infrastructure automation. Do I need Infrahub? @@ -36,7 +36,7 @@ Check out the [blog section on our website](https://opsmill.com/blog/) to learn ### How can I see Infrahub in action? -You have many options to quickly try out Infrahub, please refer to the [Getting Started](../getting-started/quick-start.mdx) page for more details. +You have many options to quickly try out Infrahub, please refer to the [Explore Infrahub](../overview/explore.mdx) page for more details. Here are some quick ways to get started: @@ -55,7 +55,7 @@ Common deployment types include: :::note -Infrahub depends on several supporting services that must be installed either within the same environment or externally. See the [Overview](../getting-started/overview.mdx) page for more details. +Infrahub depends on several supporting services that must be installed either within the same environment or externally. See the [What is Infrahub](../overview/overview.mdx) page for more details. Each deployment option comes with trade-offs. It's important to also consider your existing tools and processes when choosing the best fit. @@ -71,7 +71,7 @@ Check out the [Installing Infrahub](../guides/installation.mdx) guide for detail Once Infrahub is deployed, you can start using it to manage your infrastructure resources and begin your automation journey. -Visit the [Next Steps](../getting-started/next-steps.mdx) section for practical examples. +Visit the [Next Steps](../overview/next-steps.mdx) section for practical examples. ### What is the status of the project? Can I deploy Infrahub in production? diff --git a/docs/docs/getting-started/concepts.mdx b/docs/docs/getting-started/concepts.mdx deleted file mode 100644 index eee86b4f97..0000000000 --- a/docs/docs/getting-started/concepts.mdx +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: Concepts -description: High-Level Overview of Infrahub's Core Principles and Features ---- -import ReferenceLink from "../../src/components/Card"; -import VideoPlayer from '../../src/components/VideoPlayer'; - -## Flexible schema - -![Infrahub schema](./../media/overview-schema.excalidraw.svg) - -A core feature of Infrahub is the ability to define a relational model to describe the infrastructure, design and business logic in a way that's specific to each organization's needs, while allowing for the model to be changed via version control over time. - -The schema provides an abstraction layer to the graph database, and as such no knowledge of database administration is needed for daily Infrahub usage. - -The schema is described in YAML format, and consists of nodes, attributes, relationships, and other descriptors. For more detail, see the [guide to creating a schema](../guides/create-schema.mdx). - -A new deployment of Infrahub will have no schema by default. It is up to the administrator of the system to define and load the initial schema. See the [commands to load a schema](../topics/schema.mdx#load-a-schema-into-infrahub) for more information. - -Example schemas can be found: - -- In the [Schema Library](https://github.com/opsmill/schema-library), this is the most comprehensive collection of schemas currently maintained by the community and OpsMill. -- In the `models` directory of the [Infrahub repository](https://github.com/opsmill/infrahub/tree/develop/models) -- In other OpsMill-provided [bundle repositories](https://github.com/opsmill?q=bundle&type=all&language=&sort=) -- In other OpsMill-provided [demo repositories](https://github.com/opsmill?q=demo&type=all&language=&sort=) -- Via the Infrahub community - -The schema can be loaded into Infrahub using one of these two methods: - -- Using [`infrahubctl schema load`]($(base_url)infrahubctl/infrahubctl-load) command - This is the recommended way for development or quick testing purposes. -- Using Infrahub Git integration - This is the recommended way for production deployments as it offers better version control and collaboration features. - -Once the schema is loaded, it's stored and version controlled in the graph database, and distributed to all containers acting as Infrahub API Servers. - -Changes to the schema can be made at any time, and it's best practice to make schema changes in a branch to allow for testing before implementation. - - - -### Hands-on lab - Schema introduction - -Getting started with Infrahub and unsure about all the possibilities offered by flexible schemas? In our hands-on lab, we'll walk you through the fundamentals of this feature, enabling you to successfully shape your first schema. - -[Infrahub Schema Introduction](https://opsmill.instruqt.com/pages/labs) - -### Introduction to Schema design video - -
- -
- -### Exploring the Infrahub Schema video - -A recording of a livestream that covers: - -- What the Infrahub schema actually is -- Why we built it this way (and what we rejected) -- How it compares to other source of truth tools -- Best practices for customizing the schema to your environment - -
- -
- -## Data Transformations - -![Transformations](./../media/overview-transformations.excalidraw.svg) - -Transformations in Infrahub are operations that allow users to extract and export their infrastructure data in a structured and repeatable way. It involves converting data retrieved via GraphQL queries into a desired format, using either Jinja2 templates or Python code. - -These Transformations allow for flexible and powerful data manipulation, making it easier to integrate and utilize data in various applications and workflows. - - - -## Generators - -Generators in Infrahub are tools that automatically create infrastructure objects based on predefined templates and user inputs. They serve as a way to streamline the process of setting up complex infrastructure stacks while allowing for customization. - -Key aspects of Generators include: - -1. Template-based: Generators use templates as a starting point for creating infrastructure configurations. - -2. User input: They prompt users for specific information needed to customize the generated objects. - -3. Automation: Generators automate repetitive tasks in infrastructure setup, reducing manual effort and potential errors. - -4. Consistency: By using Generators, teams can ensure consistent infrastructure setups across different projects or environments. - -5. Customization: While based on templates, Generators allow for significant customization to meet specific project requirements. - -6. Versioning: Infrahub supports versioning of Generator outputs, enabling users to track changes over time. - -7. Integration: Generators can be integrated into workflows and CI/CD pipelines for automated infrastructure provisioning. - -8. Extensibility: Advanced users can create custom Generators to suit their organization's specific needs. - - - -## Version control - -![Infrahub Version Control](../media/overview-versioning.excalidraw.svg) - -Infrahub integrates version control directly into its graph database, providing robust capabilities for managing changes to infrastructure data. These features collectively enhance the ability to manage and control changes to infrastructure data, making Infrahub a powerful tool for infrastructure management and automation. - -### Branching and merging - -Infrahub allows you to create branches from the main data state. Each branch can contain modifications and is isolated from the main branch until changes are reviewed and merged. Branches can be created through the UI, CLI (`infrahubctl`), or GraphQL mutations. - -Changes from branches can be merged back into the main branch after review. Infrahub provides tools for viewing differences (diffs) between branches, running tests, and resolving conflicts before merging. - -### Proposed changes - -A proposed change is similar to a pull request in Git. It allows users to review and discuss changes between branches. Reviewers can leave comments, request changes, and approve the proposed change before merging. This process ensures that changes are thoroughly vetted before integration into the main branch. - -### Immutable graph and historical data - -Infrahub’s storage engine is immutable, meaning past states of the data graph are preserved. Users can query historical data to view the state of the infrastructure at any point in time. This feature is crucial for auditing and understanding the evolution of infrastructure over time. - -### Integration with Git - -Infrahub combines its graph database with Git for version control. This integration allows for synchronization between Infrahub branches and Git repositories. Users can perform typical Git operations such as commit, push, and pull within Infrahub, ensuring that data and code are versioned together. - -### Continuous integration (CI) - -Infrahub supports CI processes by running checks on proposed changes during the review process. These checks ensure data integrity and help identify potential issues before merging. Custom checks can be implemented to enforce specific business logic or operational requirements. - - - -## Conclusion - -These concepts are tightly integrated and work together to address a wide range of use cases in infrastructure management. - -### Design-driven automation and service catalog - -Having a flexible schema opens up new possibilities not previously available. Infrahub allows a business workflow or service to be implemented in the [schema](../topics/schema.mdx) and instantiated by a Generator. - -Downstream objects are linked to the Generator. If a business service needs updating or expansion, all needed changes can be generated to keep the infrastructure consistent and validated. - -For example, when deploying a new service: - - A branch is created to stage the changes - - A Generator runs and creates the needed objects according to the business logic - - A Transformation runs to create the needed configuration files - - The changes are reviewed and eventually merged in a proposed change - -:::success - -- This sets up a robust data structure that will allow lifecycle management of the service, including updates, decommissioning, and more. -- Capturing business logic in the Generator enables consistent and repeatable deployments, reducing the risk of human error. - -::: - - - -### Agility in infrastructure management - -Some changes in the infrastructure can be complex and require careful planning and testing. Infrahub's version control capabilities allow for these changes to be staged and tested in isolation before being applied to the production environment. - -For example, during a large network software upgrade: - - A branch is created to stage the changes - - Any changes to the schema can be made in the branch, such as adding a new attribute - - Transformations and templates are updated to use the new attribute - - Data is populated in the branch - - Artifacts are generated to reflect the new state of the infrastructure - - Tests are run to ensure the changes work as expected - - The changes are collaboratively reviewed in a proposed change - - During the maintenance window, the branch is merged and the changes are applied to the production environment - -:::success - -- Branching allows for complex changes to be prepared in advance without holding back your production, reducing the risk of downtime or errors. -- The proposed change process enables collaboration and review, while the integrated CI pipeline ensures that changes are tested and artifacts are generated. - -::: diff --git a/docs/docs/getting-started/next-steps.mdx b/docs/docs/getting-started/next-steps.mdx deleted file mode 100644 index bea3fe9109..0000000000 --- a/docs/docs/getting-started/next-steps.mdx +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Next Steps ---- -import ReferenceLink from "../../src/components/Card"; - -Now that you know more about the project, this page will guide you through the key steps to run and develop your own instance of Infrahub. - -## 1. Installation - -Infrahub supports multiple installation options. Choose the one that best fits your environment: - -- **Docker Compose**: A quick way to run Infrahub on any machine with Docker installed. -- **Kubernetes**: Ideal for running in production or cloud environments. -- **Invoke**: Clone the repository and run it locally for development purposes. - -:::note Hardware Requirements - -Make sure your machine meets the hardware requirements for running Infrahub. Find the requirements in the [related topic](../topics/hardware-requirements.mdx). - -::: - - - -Additionally, you might want to install the Infrahub CLI tool on your laptop. This is a Python package that provides a command-line interface to interact with your Infrahub instance. The CLI is useful for loading data, managing schemas, and performing other administrative tasks. - - - -## 2. The schema - -Everything starts with data. The schema defines the shape of your data and drives the rest of the system. - -Starting from a blank page might feel overwhelming, also some parts are quite common in many organizations, so why reinvent the wheel? To address this challenge OpsMill and the community are sharing and maintaining a collection of schema in the [**Schema Library**](https://github.com/opsmill/schema-library). - -This is the perfect starting point to quickly scaffold a schema that will cover the common parts of your infrastructure data. You can also reference it to craft your own custom schema! - - - -## 3. Load data - -With a schema in place, it's time to bring in some data. If you have existing systems that hold your infrastructure data, we provide you the tool to sync them with Infrahub. - -At the moment [**Infrahub Sync**](https://github.com/opsmill/infrahub-sync) supports the following adapters: - -- IP Fabric -- LibreNMS -- Nautobot -- Netbox -- Observium -- Peering Manager -- Slurp'it - - - -Alternatively, you can describe your data in a structured YAML format and load it directly into Infrahub. This is useful for initial data seeding or for small datasets. - -```yaml ---- -apiVersion: infrahub.app/v1 -kind: Object -spec: - kind: LocationCity - data: - - name: denver - shortname: den1 - - name: paris - shortname: par1 -``` - -You can then load this data using the Infrahub CLI: - -```bash -infrahubctl object load city_data.yml -``` - - - -## 4. Initialize a git repository - -The git repository will be used to store any files needed to capture the intended state of your infrastructure, such as the schema, templates, Python scripts, etc. - -Infrahub offers a native integration with git, allowing you to connect your repository and consume the files to run data transformations, Generators, and more. - -The most important file is the `.infrahub.yml` file, which defines how Infrahub should behave and what files to consume. - -You will need to push this repository to a remote location that Infrahub can access. It doesn't have to be a public repository as Infrahub supports authentication with private repositories. Depending on the provider you use (for example: GitHub, GitLab, Bitbucket), the process may vary slightly, but the general steps are the same: - -1. Create a new repository using copier (or manually). More details in the [developer guide](../topics/developer-guide.mdx#initializing-an-infrahub-repository). - -```shell -uv tool run --from 'copier' copier copy https://github.com/opsmill/infrahub-template -``` - -2. Push the repository to the remote location. -3. Create an access token with the required permissions to access the repository. - -Then you can connect the repository to Infrahub using the Infrahub CLI or the web interface! - - - -## Going further - -:::success - -At this point, you have a running Infrahub instance with a schema, some data loaded and a git repository ready to be used. Congratulations! You are now ready to explore the next steps in your Infrahub journey. - -::: - -From here, depending on your use case and goals, you can: - -- [**Create your own schema**](../guides/create-schema.mdx) - Extend the existing schema to fit your organization's needs. -- [**Generate artifacts**](../guides/artifact.mdx) - Use Transformations to create meaningful files from your data such as startup configurations, documentation, cabling plans and more. -- [**Build Generators**](../guides/generator.mdx) - Automate the creation of infrastructure objects based on templates and user inputs. -- [**Deploy artifacts to the field using Ansible**]($(base_url)ansible) - Deploy outputs where they're needed and apply your intended state to your infrastructure. You can also use other tools like [Nornir]($(base_url)nornir) to deploy your artifacts. - -If you need guidance with which feature to explore next or how to implement a specific use case, feel free to reach out to the community on our [Discord server](https://discord.gg/opsmill) or book a meeting with OpsMill. - - diff --git a/docs/docs/getting-started/overview.mdx b/docs/docs/getting-started/overview.mdx deleted file mode 100644 index e46492e66f..0000000000 --- a/docs/docs/getting-started/overview.mdx +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: Overview -description: An Introduction to Infrahub's Vision, Core Features, and Infrastructure Data Management Approach. ---- - -Infrahub from [OpsMill](https://opsmill.com) takes a new approach to Infrastructure Management by providing a modern datastore to organize and control all the data that defines how infrastructure should run. Infrahub offers a central hub to manage the data and code that powers your infrastructure. It combines the version control and branch management capabilities similar to Git with the flexible data model and UI of a graph database. - -With Infrahub, you can: - -- **Unify All Your Data**: Model services, synchronize infrastructure data, and manage intent in a fully customizable schema with no constraints. -- **Version and Validate**: Version and validate everything from design through deploy with native continuous integration tools. -- **Deploy Flexibly**: Use whatever configuration automation and deployment validation tools you want via Infrahub integrations. - -![Infrahub architecture](./../media/overview.excalidraw.svg) - -At its heart, Infrahub is built on 3 fundamental pillars: - -- **A Flexible Schema**: A model of the infrastructure and the relation between the objects in the model, that is easily extensible. -- **Version Control**: Natively integrated into the graph database, enabling new capabilities such as branching, diffing, and merging data directly in the database. -- **Unified Storage**: By combining a graph database and git, Infrahub stores data and code needed to manage the infrastructure. - -## Interfaces - -![Infrahub interfaces](./../media/overview-interfaces.excalidraw.svg) - -Managing infrastructure at scale often means many people, teams, workflows and other systems must interact with the Infrahub infrastructure management platform. Infrahub provides multiple methods to interact: - -### WebUI - -- By default, exposed on TCP port `8000` -- Built-in documentation -- Global search, including searching data and documentation -- A GraphQL sandbox -- Swagger documentation for the REST API - -### GraphQL API - -GraphQL is the primary API to interact with data, and allows access to everything defined by the schema. The [Python SDK]($(base_url)python-sdk/introduction) is built on top of the GraphQL API. - -- By default, exposed on TCP port `8000` at the endpoint: `http://:8000/graphql` -- The Frontend utilizes the GraphQL API for most tasks -- More information can be found in the [GraphQL topic](../topics/graphql.mdx) - -### REST API - -GraphQL only accepts queries in string format and returns JSON, so certain workflows are available exclusively via the REST API. - -- Loading the schema -- Retrieving artifacts -- Accessing the object store -- Executing a saved GraphQL query - -The REST API has the following properties: - -- By default, exposed on TCP port `8000` at the endpoint: `http://:8000/api` -- Swagger docs can be found at: `http://:8000/api/docs` - -### infrahubctl - -`infrahubctl` is a command line utility designed to help with the day to day management of an Infrahub installation. It's meant to run on any laptop or server and it communicates with a remote Infrahub server over the network. - -More information can be found in the [infrahubctl]($(base_url)infrahubctl/infrahubctl) documentation section. - -### Python SDK - -The Infrahub Python SDK greatly simplifies how you can interact with Infrahub programmatically. - -More information can be found in the [Python SDK]($(base_url)python-sdk/introduction) documentation section. - -### Git - -One of the three pillars Infrahub is built on is the idea of having unified storage for data and code. The data is stored in the graph database and the code is stored in Git. - -When integrating a Git repository with Infrahub, the Task worker will ensure that both systems stay in sync at any time. Changes to branches or files in a Git repository will be synced to Infrahub automatically. - -More information can be found in the [external repositories guide](../guides/repository.mdx) - -## Data input and sync - -![Infrahub data input and sync](./../media/overview-data.excalidraw.svg) - -When a schema has been loaded into Infrahub, data can be populated or synced through multiple methods: - -- Via the WebUI: users can add, modify, and delete objects -- Via [infrahub-sync]($(base_url)sync) -- Via YAML based [object files]($(base_url)python-sdk/topics/object_file) -- Via the [Infrahub SDK]($(base_url)python-sdk/introduction), which simplifies working with the GraphQL API: - - One-time imports can be done similar to this [Python example](https://github.com/opsmill/infrahub-bundle-dc/blob/main/scripts/create_users_roles.py) - - Integration with other systems -- Via the GraphQL or REST API directly - -Infrahub provides [data lineage and metadata](../topics/metadata.mdx) for tracking the origin and ownership of the data, and how the data changes and moves over time. When data comes from other systems and creates objects in the Infrahub database, those objects will have attributes such as its source and whether it is read-only, allowing for unidirectional sync from other sources of truth. - -## Deployment - -While Infrahub stores data and uses Transformations to generate configuration artifacts, it does not directly deploy configurations to devices. Instead, it integrates with tools like Nornir and Ansible, or triggers external orchestration platforms via webhooks for event-driven workflows. - -These integrations transform Infrahub into a centralized source of truth for infrastructure data, leveraging the automation capabilities of Ansible and Nornir to streamline management and ensure efficiency and precision. - -### Ansible integration - -This integration is provided through the [`opsmill.infrahub` Ansible Collection]($(base_url)ansible/). It allows Infrahub to be used as a dynamic inventory source for Ansible, enabling management of infrastructure based on data stored in Infrahub. - -### Nornir integration - -Nornir is a Python-based automation framework primarily used for network automation. The [Infrahub plugin for Nornir]($(base_url)nornir/) enables Infrahub to serve as an inventory source, providing a streamlined solution for managing network devices and configurations. - -### Webhooks - -Infrahub can trigger outbound [webhooks](../topics/webhooks.mdx) as part of its event-driven automation workflows. These webhooks can be configured to notify or trigger actions in external orchestration platforms whenever changes occur to relevant data or artifacts within Infrahub. This allows seamless integration into larger automation pipelines. - -### Key features - -- **Inventory Management**: Infrahub can dynamically generate and update inventories for Ansible and Nornir, ensuring that the latest state of infrastructure is always used. -- **Automation**: By leveraging each framework's automation capabilities, users can execute complex infrastructure management tasks directly using Infrahub data. -- **Configuration Deployment**: These integrations ensure that configurations managed by Infrahub are consistent across the infrastructure by applying them through Ansible, Nornir or webhooks. diff --git a/docs/docs/home.mdx b/docs/docs/home.mdx index bb403cf107..badc405890 100644 --- a/docs/docs/home.mdx +++ b/docs/docs/home.mdx @@ -16,18 +16,18 @@ import HomePageCard from "../src/components/HomePage/card.tsx"; title="Overview" svgPath="/img/infrahub-logo.svg" description="An introduction to Infrahub's vision, core features, and infrastructure data management approach." - link="getting-started/overview" + link="overview" /> - diff --git a/docs/docs/overview/concepts.mdx b/docs/docs/overview/concepts.mdx new file mode 100644 index 0000000000..1d3c5cba10 --- /dev/null +++ b/docs/docs/overview/concepts.mdx @@ -0,0 +1,118 @@ +--- +title: Key Concepts +description: Core principles behind Infrahub — flexible schemas, version control, Transformations, Generators, and design-driven automation. +--- +import ReferenceLink from "../../src/components/Card"; + +## Flexible schema + +![Infrahub schema](./../media/overview-schema.excalidraw.svg) + +A core feature of Infrahub is the ability to define a relational model to describe the infrastructure, design and business logic in a way that's specific to each organization's needs, while allowing for the model to be changed via version control over time. + +The schema provides an abstraction layer to the graph database, and as such no knowledge of database administration is needed for daily Infrahub usage. + +The schema is described in YAML format, and consists of nodes, attributes, relationships, and other descriptors. A new deployment of Infrahub will have no schema by default — it is up to the administrator to define and load the initial schema. + +Example schemas can be found in the [Schema Library](https://github.com/opsmill/schema-library), the most comprehensive collection currently maintained by the community and OpsMill. + +The schema can be loaded using the [`infrahubctl schema load`]($(base_url)infrahubctl/infrahubctl-load) command for development, or via Infrahub Git integration for production deployments. Once loaded, it's stored and version controlled in the graph database. Changes to the schema can be made at any time, and it's best practice to make schema changes in a branch to allow for testing before implementation. + + + +## Transformations + +![Transformations](./../media/overview-transformations.excalidraw.svg) + +Transformations allow users to extract and export infrastructure data in a structured and repeatable way. They convert data retrieved via GraphQL queries into a desired format, using either Jinja2 templates or Python code. + +These Transformations allow for flexible and powerful data manipulation, making it easier to integrate and utilize data in various applications and workflows — from generating device configurations to producing documentation or compliance reports. + + + +## Generators + +Generators automatically create infrastructure objects based on predefined templates and user inputs. They streamline the setup of complex infrastructure stacks while allowing for customization. + +Generators use templates as a starting point and prompt users for specific information to customize the output. This automates repetitive tasks, reduces manual effort, and ensures consistent infrastructure setups across projects and environments. Generator outputs are versioned, enabling users to track changes over time. + +Advanced users can create custom Generators to suit their organization's specific needs and integrate them into workflows and CI/CD pipelines for automated infrastructure provisioning. + + + +## Version control + +![Infrahub Version Control](../media/overview-versioning.excalidraw.svg) + +Infrahub integrates version control directly into its graph database, providing robust capabilities for managing changes to infrastructure data. + +### Branching and merging + +Infrahub allows you to create branches from the main data state. Each branch can contain modifications and is isolated from the main branch until changes are reviewed and merged. Branches can be created through the UI, CLI (`infrahubctl`), or GraphQL mutations. + +Changes from branches can be merged back into the main branch after review. Infrahub provides tools for viewing differences (diffs) between branches, running tests, and resolving conflicts before merging. + +### Proposed changes + +A proposed change is similar to a pull request in Git. It allows users to review and discuss changes between branches. Reviewers can leave comments, request changes, and approve the proposed change before merging. This process ensures that changes are thoroughly vetted before integration into the main branch. + +### Immutable graph and historical data + +Infrahub's storage engine is immutable, meaning past states of the data graph are preserved. Users can query historical data to view the state of the infrastructure at any point in time. This feature is crucial for auditing and understanding the evolution of infrastructure over time. + +### Integration with Git + +Infrahub combines its graph database with Git for version control. This integration allows for synchronization between Infrahub branches and Git repositories. Users can perform typical Git operations such as commit, push, and pull within Infrahub, ensuring that data and code are versioned together. + +### Continuous integration (CI) + +Infrahub supports CI processes by running checks on proposed changes during the review process. These checks ensure data integrity and help identify potential issues before merging. Custom checks can be implemented to enforce specific business logic or operational requirements. + + + +## Putting it together + +These concepts are tightly integrated and work together to address a wide range of use cases in infrastructure management. + +### Design-driven automation and service catalog + +Having a flexible schema opens up new possibilities not previously available. Infrahub allows a business workflow or service to be implemented in the [schema](../topics/schema.mdx) and instantiated by a Generator. + +Downstream objects are linked to the Generator. If a business service needs updating or expansion, all needed changes can be generated to keep the infrastructure consistent and validated. + +For example, when deploying a new service: + +- A branch is created to stage the changes +- A Generator runs and creates the needed objects according to the business logic +- A Transformation runs to create the needed configuration files +- The changes are reviewed and eventually merged in a proposed change + +:::success + +- This sets up a robust data structure that will allow lifecycle management of the service, including updates, decommissioning, and more. +- Capturing business logic in the Generator enables consistent and repeatable deployments, reducing the risk of human error. + +::: + + + +### Agility in infrastructure management + +Some changes in the infrastructure can be complex and require careful planning and testing. Infrahub's version control capabilities allow for these changes to be staged and tested in isolation before being applied to the production environment. + +For example, during a large network software upgrade: + - A branch is created to stage the changes + - Any changes to the schema can be made in the branch, such as adding a new attribute + - Transformations and templates are updated to use the new attribute + - Data is populated in the branch + - Artifacts are generated to reflect the new state of the infrastructure + - Tests are run to ensure the changes work as expected + - The changes are collaboratively reviewed in a proposed change + - During the maintenance window, the branch is merged and the changes are applied to the production environment + +:::success + +- Branching allows for complex changes to be prepared in advance without holding back your production, reducing the risk of downtime or errors. +- The proposed change process enables collaboration and review, while the integrated CI pipeline ensures that changes are tested and artifacts are generated. + +::: diff --git a/docs/docs/getting-started/quick-start.mdx b/docs/docs/overview/explore.mdx similarity index 79% rename from docs/docs/getting-started/quick-start.mdx rename to docs/docs/overview/explore.mdx index febbd2a817..378636d2ea 100644 --- a/docs/docs/getting-started/quick-start.mdx +++ b/docs/docs/overview/explore.mdx @@ -1,23 +1,36 @@ --- -title: Quick Start +title: Explore Infrahub +description: See Infrahub in action through the sandbox, interactive labs, videos, and demos. --- import VideoPlayer from '../../src/components/VideoPlayer'; import ReferenceLink from "../../src/components/Card"; To see Infrahub in action, you have several options. Depending on your available time and preferred learning style, you can choose from the following — ranging from the quickest to the most in-depth experience: +- **[Infrahub sandbox](#infrahub-sandbox)** - A public instance of Infrahub that you can explore right now. +- **[Getting started lab](#getting-started-lab)** - Interactive lab that covers the basic concepts of Infrahub. - **[Videos](#videos)** - A series of short videos that provide an overview of Infrahub and its capabilities. -- **[Infrahub sandbox](#infrahub-sandbox)** - A public instance of Infrahub that you can use to explore the platform. -- **[Getting started lab](#getting-started-lab)** - Interactive lab that explores the basic concepts of Infrahub. -- **[Infrahub demos](#infrahub-bundles-and-demos)** - Full-blown demo of Infrahub that showcases its capabilities in specific business scenarios. -- **[Meeting OpsMill](#meeting-opsmill)** - Book a session with OpsMill to discuss your use case and how Infrahub can help you. +- **[Infrahub demos](#infrahub-bundles-and-demos)** - Full-blown demos that showcase Infrahub's capabilities in specific business scenarios. +- **[Meeting OpsMill](#meeting-opsmill)** - Book a session with OpsMill to discuss your use case. :::note -If you are looking to build your own Infrahub instance to evaluate it in your environment, please refer to the [Next steps](./next-steps.mdx) section! +If you are looking to build your own Infrahub instance, head to the [Quick Start](./quickstart.mdx) or [Next steps](./next-steps.mdx) section. ::: +## Infrahub sandbox + +The Infrahub Sandbox is a publicly hosted version of Infrahub, pre-loaded with sample data and examples. It's a great way to explore and get a first look at the Infrahub UI. + + + +## Getting started lab + +No configuration or installation needed! In this lab, we'll guide you through the fundamentals of Infrahub and how to use it effectively. Version control, flexible schemas, and Git integration are all on the menu for this action-packed 30-minute session. + + + ## Videos Find below a selection of videos that provide an overview of Infrahub and its capabilities. More videos are available on the [OpsMill YouTube channel](https://www.youtube.com/@OpsMill). @@ -34,19 +47,21 @@ Find below a selection of videos that provide an overview of Infrahub and its ca - +### Introduction to schema design -## Infrahub sandbox - -The Infrahub Sandbox is a publicly hosted version of Infrahub, pre-loaded with sample data and examples. It's a great way to explore and get a first look at the Infrahub UI! +
+ +
- +### Exploring the Infrahub schema -## Getting started lab +A recording of a livestream that covers what the Infrahub schema actually is, why it was built this way, how it compares to other source of truth tools, and best practices for customizing the schema to your environment. -No configuration or installation needed! In this lab, we'll guide you through the fundamentals of Infrahub and how to use it effectively. Version control, flexible schemas, and Git integration are all on the menu for this action-packed 30-minute session. +
+ +
- + ## Infrahub bundles and demos diff --git a/docs/docs/overview/next-steps.mdx b/docs/docs/overview/next-steps.mdx new file mode 100644 index 0000000000..ceaded71b9 --- /dev/null +++ b/docs/docs/overview/next-steps.mdx @@ -0,0 +1,60 @@ +--- +title: Next Steps +description: Turn your local Infrahub setup into a proof of concept for your organization. +--- +import ReferenceLink from "../../src/components/Card"; + +If you completed the [Quick Start](./quickstart.mdx), you have a local Infrahub instance with a sample schema and some data. This page outlines the key steps to turn that into a proof of concept that demonstrates value to your organization. + +## 1. Design your schema + +The Quick Start used pre-built schemas from the Schema Library. For a POC, model a slice of your actual infrastructure — the devices, services, or resources that matter most to your team. + +Start with a focused scope. Pick one domain (for example: data center fabric, WAN sites, or firewall policies) and model it. You can always expand later. The [Schema Library](https://github.com/opsmill/schema-library) remains a good starting point to extend from. + + + +## 2. Load real data + +With a schema that reflects your infrastructure, bring in real data. If you already have a source of truth (Netbox, Nautobot, IP Fabric, or others), [Infrahub Sync](https://github.com/opsmill/infrahub-sync) can pull data from these systems directly. + +Alternatively, describe your data in YAML object files and load them with `infrahubctl`, the same way you did in the Quick Start. This works well for initial seeding or for data that doesn't live in another system yet. + + + +## 3. Connect a Git repository + +In the Quick Start, schemas and data files lived on your local machine. For a POC, store them in a Git repository and connect it to Infrahub. This unlocks Git-native workflows: Infrahub will sync branches, track changes, and consume files like Jinja2 templates and Python scripts directly from the repository. + +Push the project created during the Quick Start to a remote repository (GitHub, GitLab, Bitbucket, etc.) and connect it through the UI or CLI. + + + +## 4. Generate artifacts + +Once you have real data and a connected repository, use Transformations to generate outputs from your data — device configurations, cabling plans, documentation, compliance reports, or anything else your team needs. + +This is where Infrahub starts delivering tangible value: a single data change can regenerate all affected artifacts automatically. + + + +## 5. Deploy to a shared environment + +A local Docker setup works for development, but for a POC that involves your team, deploy Infrahub to a shared environment. Infrahub is packaged as Docker images and supports multiple deployment options: + +- **Docker Compose** on a shared VM for quick team access +- **Kubernetes** via Helm Chart for production-grade deployments + + + +## Going further + +At this point, you have a running Infrahub instance with your own schema, real data, a connected Git repository, and generated artifacts. From here you can: + +- [Build Generators](../guides/generator.mdx) to automate the creation of infrastructure objects from templates and business logic. +- [Set up events and webhooks](../guides/events-rules-actions.mdx) to trigger external systems when data changes. +- [Deploy artifacts with Ansible]($(base_url)ansible) or [Nornir]($(base_url)nornir) to push configurations to your infrastructure. + +If you need guidance on which feature to explore next or how to implement a specific use case, reach out to the community on [Discord](https://discord.gg/opsmill) or book a meeting with OpsMill. + + diff --git a/docs/docs/overview/overview.mdx b/docs/docs/overview/overview.mdx new file mode 100644 index 0000000000..f67951c132 --- /dev/null +++ b/docs/docs/overview/overview.mdx @@ -0,0 +1,65 @@ +--- +title: What is Infrahub +description: A graph-based infrastructure data management platform with built-in version control, CI workflows, peer review, and API access. +--- + +Infrahub is a graph-based data management platform with built-in version control, CI workflows, peer review, and API access. It's purpose-built to power network, data center, and cloud automation. + +Infrahub provides a single platform that unifies infrastructure data with business logic, enforces consistency, and integrates with automation tools and AI workflows. With Infrahub as the data foundation in your automation stack, you can move faster, reduce risk, and deliver infrastructure as a reliable service. + +![Infrahub architecture](./../media/overview.excalidraw.svg) + +## Top ways to use Infrahub + +### Unify infrastructure data + +Sync network and infrastructure device, service, and policy data into a unified source of truth, with rich metadata and robust UI and API access. + +### Automate at scale + +Generate, validate, and deploy configurations with unified data. Support full lifecycle management — provisioning, upgrades, decommissioning — across vendors and sites. + +### Enable self-service + +Expose automation through catalogs and APIs so application, platform, and ops teams can request infrastructure directly. Speed time to delivery, reduce errors, and make infrastructure more responsive to the business. + +### Build an AIOps knowledge graph + +Model dependencies and relationships across infrastructure. Provide the data foundation for AI-driven reasoning, troubleshooting, and predictive operations. + +## Core pillars + +At its heart, Infrahub is built on 3 fundamental pillars: + +- **A Flexible Schema**: A model of the infrastructure and the relation between the objects in the model, that is easily extensible. +- **Version Control**: Natively integrated into the graph database, enabling capabilities such as branching, diffing, and merging data directly in the database. +- **Unified Storage**: By combining a graph database and Git, Infrahub stores data and code needed to manage the infrastructure. + +## Interfaces + +![Infrahub interfaces](./../media/overview-interfaces.excalidraw.svg) + +Managing infrastructure at scale often means many people, teams, workflows and other systems must interact with the platform. Infrahub provides multiple methods to interact: + +| Interface | Description | +|---|---| +| **WebUI** | Browser-based interface on port `8000` with built-in documentation, global search, a GraphQL sandbox, and Swagger docs. | +| **GraphQL API** | Primary data API for everything defined by the schema. The Frontend and [Python SDK]($(base_url)python-sdk/introduction) are built on top of it. Endpoint: `/graphql` | +| **REST API** | Used for schema loading, artifact retrieval, object storage, and executing saved GraphQL queries. Endpoint: `/api` | +| **infrahubctl** | CLI tool for day-to-day management of an Infrahub installation. Runs on any machine and communicates with a remote server. [Reference]($(base_url)infrahubctl/infrahubctl) | +| **Python SDK** | Programmatic access to Infrahub for scripts, integrations, and automation. [Documentation]($(base_url)python-sdk/introduction) | +| **Git** | Native integration with Git repositories. The Task worker keeps both systems in sync — changes to branches or files in a Git repository are synced to Infrahub automatically. [Guide](../guides/repository.mdx) | + +## Data input and sync + +![Infrahub data input and sync](./../media/overview-data.excalidraw.svg) + +Once a schema is loaded, data can be populated or synced through multiple methods: the WebUI, [infrahub-sync]($(base_url)sync) for integration with external systems (Netbox, Nautobot, IP Fabric, and more), YAML-based [object files]($(base_url)python-sdk/topics/object_file), the [Python SDK]($(base_url)python-sdk/introduction), or the GraphQL/REST APIs directly. + +Infrahub provides [data lineage and metadata](../topics/metadata.mdx) for tracking the origin and ownership of data, and how it changes over time. When data comes from external systems, those objects carry attributes such as their source and whether they are read-only, enabling unidirectional sync from other sources of truth. + +## Deployment + +While Infrahub stores data and uses Transformations to generate configuration artifacts, it does not directly deploy configurations to devices. Instead, it integrates with tools like [Ansible]($(base_url)ansible/), [Nornir]($(base_url)nornir/), or triggers external orchestration platforms via [webhooks](../topics/webhooks.mdx) for event-driven workflows. + +These integrations transform Infrahub into a centralized source of truth for infrastructure data, leveraging existing automation tools to streamline management and ensure consistency across the infrastructure. diff --git a/docs/docs/overview/quickstart.mdx b/docs/docs/overview/quickstart.mdx new file mode 100644 index 0000000000..5b30667b84 --- /dev/null +++ b/docs/docs/overview/quickstart.mdx @@ -0,0 +1,229 @@ +--- +title: Quick Start +description: Set up a local Infrahub instance, load a data model, create infrastructure data, and explore branching. +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import ReferenceLink from "../../src/components/Card"; + +In this tutorial, you will set up a local Infrahub instance on your machine, load a schema that defines your data model, create infrastructure objects, and explore branching. By the end, you will have a working environment with real data you can interact with. + +This quick start serves a dual purpose: it teaches you the fundamentals of Infrahub — schemas, `infrahubctl`, and branching — and it sets up a local development environment that you can continue building on as you go deeper. + +**Time**: ~30 minutes + +**What you will build**: A running Infrahub instance with a network location data model, location data, and a branch with proposed changes. + +:::note +Running Infrahub locally with Docker is the most convenient setup for development and experimentation, but it requires a machine with adequate resources. See [hardware requirements](../topics/hardware-requirements.mdx) for details. If you prefer a lighter option, try the [Infrahub Sandbox](https://sandbox.infrahub.app/) or the [Getting Started Lab](https://opsmill.instruqt.com/pages/labs) instead. +::: + +**Prerequisites**: + +- [Docker](https://docs.docker.com/get-docker/) installed and running (Docker Desktop or OrbStack) +- [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python package manager) +- [Python 3.10+](https://www.python.org/downloads/) + +## Create a project + +[Copier](https://copier.readthedocs.io/) is a project scaffolding tool. Use it to create a new Infrahub project from the official template, which includes the standard file structure, task definitions, and a `schemas/` folder: + +1. Run the following command to create a new project directory: + +```bash +uv tool run --from 'copier' copier copy https://github.com/opsmill/infrahub-template infrahub-automation +``` + +If you are unsure about the options, accept the default values for all prompts by pressing **Y**. + +2. Navigate to the project directory: + +```bash +cd infrahub-automation +``` + +3. Open the project in your IDE. If you have Visual Studio Code installed, you can run: + +```bash +code . +``` + +:::success Verification +Run `ls` in the project directory. You should see files including `pyproject.toml`, `tasks.py`, and a `schemas/` folder. +::: + +## Start Infrahub + +The project template includes [Invoke](https://www.pyinvoke.org/) tasks that wrap Docker Compose commands. + +1. Start all Infrahub services with a single command: + +```bash +uv run invoke start +``` + +The first run takes a few minutes while Docker downloads the container images. + +2. Open your browser and go to [http://localhost:8000](http://localhost:8000). + +3. Log in from the bottom-left corner using the default credentials: + + - Username: `admin` + - Password: `infrahub` + +:::success Verification +You should see the Infrahub web interface with a navigation menu on the left side. +::: + +## Load a schema + +A schema defines the structure of your infrastructure data in Infrahub — the types of objects, their attributes, and how they relate to each other. [Learn more about schemas](../topics/schema.mdx). + +Rather than writing a schema from scratch, use the [Schema Library](https://github.com/opsmill/schema-library), a community-maintained collection of reusable data models. + +1. Download the schema library: + +```bash +uv run invoke schema-library-get +``` + +2. Explore the downloaded schema files in the `schema-library/` folder in your IDE. + +:::info +- The schema library is divided into a `base/` with core definitions and `extensions/` that build on top of the base. You need to load the base to add extensions. +- Since you have access to the full schema code, you can explore and modify the schemas to fit your organization's needs. +::: + +3. Load the schema into your project: + +:::info +To keep things organized, put all schema files in a `schemas/` folder in your project and load them from there. Copy the files you need from the `schema-library/` folder into your project's `schemas/` folder. +::: + +```bash +uv run infrahubctl schema load schemas/ +``` + +:::success Verification +Go back to [http://localhost:8000](http://localhost:8000) and refresh the page. The left-hand menu should now display new items including location types like **Country** and **Site**. +::: + +## Create your first data + +There are multiple ways to create data in Infrahub — the WebUI, APIs, Python SDK, and more. For development purposes, it's often easiest to create YAML files and load them with `infrahubctl`. + +1. Create a file called `countries.yml` in the `objects/` folder with the following content: + +```yaml +--- +apiVersion: infrahub.app/v1 +kind: Object +spec: + kind: LocationCountry + data: + - name: United States + shortname: US + description: US operations + children: + kind: LocationMetro + data: + - name: Denver + shortname: DEN + - name: France + shortname: FR + description: EU operations + children: + kind: LocationMetro + data: + - name: Paris + shortname: PAR +``` + +2. Load the data into Infrahub: + +```bash +uv run infrahubctl object load objects/countries.yml +``` + +:::success Verification +Go to [http://localhost:8000](http://localhost:8000) and navigate to the **Country** list in the left-hand menu. You should see **United States** and **France**. Click on **United States** to view its details. +::: + +## Explore branching + +Branches in Infrahub work like Git branches — they let you stage changes in isolation without affecting the main dataset. This is one of Infrahub's most powerful features: you can propose, review, and test data changes before merging them. [Learn more about branching](../topics/branching.mdx). + +1. Create a branch called `add-locations`: + + + + + ```bash + uv run infrahubctl branch create add-locations + ``` + + + + Create an `add-locations` branch using the branch selector in the top-left corner of the WebUI. + + + +2. Add sites in the `add-locations` branch: + + + + + 3. Create a file called `sites.yml` in the `objects/` folder: + + ```yaml + --- + apiVersion: infrahub.app/v1 + kind: Object + spec: + kind: LocationSite + data: + - name: Denver DC1 + shortname: DEN1 + description: Primary US data center + parent: DEN + - name: Paris DC1 + shortname: PAR1 + description: Primary EU data center + parent: PAR + ``` + + 4. Load the sites into the `add-locations` branch: + + ```bash + uv run infrahubctl object load objects/sites.yml --branch add-locations + ``` + + Notice the `--branch` flag — this targets the branch instead of main. + + + + - Switch to the `add-locations` branch in the WebUI. + - Using the left-hand menu, navigate to the **Site** list and click the "Create Site" button. + - Create new **Site** objects for **Denver DC1** and **Paris DC1** using the UI forms. + + + +:::success Verification +Go to [http://localhost:8000](http://localhost:8000). In the top-left corner, use the branch selector to switch to the **add-locations** branch. Navigate to the **Site** list in the left-hand menu. You should see **Denver DC1** and **Paris DC1**. + +Switch back to the **main** branch. The sites are not visible because they only exist in the `add-locations` branch. +::: + +## Next steps + +You now have a working Infrahub development environment. You know how to: + +- Start a local Infrahub instance +- Load a schema to define your data model +- Create infrastructure objects from YAML files +- Use branches to isolate changes from the main dataset + +The [Next Steps](./next-steps.mdx) guide walks you through turning this local setup into a proof of concept for your organization — from designing your own schema to generating artifacts and deploying to a shared environment. + + diff --git a/docs/docs/topics/hardware-requirements.mdx b/docs/docs/topics/hardware-requirements.mdx index d5614c5962..e4295753f5 100644 --- a/docs/docs/topics/hardware-requirements.mdx +++ b/docs/docs/topics/hardware-requirements.mdx @@ -6,7 +6,7 @@ import EnterpriseBadge from '@site/src/components/EnterpriseBadge'; This page outlines the hardware requirements for running Infrahub, including minimum and recommended specifications, enterprise sizing, cloud provider machine types, and a utility for benchmarking your system's performance. -If you only want to try Infrahub, follow the [quick start](../getting-started/quick-start.mdx). +If you only want to try Infrahub, follow the [Quick Start](../overview/quickstart.mdx). ## General hardware requirements diff --git a/docs/sidebars.ts b/docs/sidebars.ts index a95448ad29..185fc3ad14 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -5,14 +5,18 @@ const sidebars: SidebarsConfig = { "home", { type: 'category', - label: 'Getting Started', + label: 'Overview', collapsed: false, collapsible: false, + link: { + type: 'doc', + id: 'overview/overview', + }, items: [ - 'getting-started/overview', - 'getting-started/quick-start', - 'getting-started/next-steps', - 'getting-started/concepts', + 'overview/concepts', + 'overview/explore', + 'overview/quickstart', + 'overview/next-steps', ], }, { diff --git a/docs/src/components/HomePage/header.tsx b/docs/src/components/HomePage/header.tsx index c263ed0f89..43f9bf6530 100644 --- a/docs/src/components/HomePage/header.tsx +++ b/docs/src/components/HomePage/header.tsx @@ -27,7 +27,7 @@ export default function HomepageHeader() {
{translate({ id: 'home.header.docs',