Serviços de Rede Omnitouch - Sistema de Implantação Ansible

Visão Geral

Este repositório contém playbooks, funções e configurações do Ansible para implantar soluções completas de rede celular (4G EPC, 5G Core, IMS, SS7) dos Serviços de Rede Omnitouch. O sistema permite implantações automatizadas e repetíveis de infraestrutura de telecomunicações de nível de produção.

O Que é Implantado

OmniCore (Plataforma de Core de Pacotes 4G/5G)

• OmniHSS - Servidor de Assinantes Residenciais
• OmniSGW - Gateway de Serviço (plano de controle)
• OmniPGW - Gateway de Pacotes (plano de controle)
• OmniUPF - Função do Plano do Usuário
• OmniDRA - Agente de Roteamento Diameter
• OmniTWAG - Gateway de Acesso WLAN Confiável

Veja: https://docs.omnitouch.com.au/docs/repos/OmniCore

OmniCall (Plataforma de Voz e Mensagens)

• OmniCall CSCF - Controle de Sessão de Chamadas (P-CSCF, I-CSCF, S-CSCF)
• OmniTAS - Servidor de Aplicações IMS (VoLTE, VoNR, VoWiFi)
• OmniMessage - Centro de SMS (SMS-C)
• OmniMessage SMPP - Suporte ao protocolo SMPP
• OmniSS7 - Componentes de sinalização SS7 (STP, HLR, CAMEL)
• VisualVoicemail - Funcionalidade de correio de voz

Veja: https://docs.omnitouch.com.au/docs/repos/OmniCall

OmniCharge/OmniCRM

• OmniCRM - Gestão de relacionamento com o cliente, autoinscrição, faturamento

Veja: https://docs.omnitouch.com.au/docs/repos/OmniCharge

Serviços de Suporte

• License Server - Licenciamento centralizado
• DNS - Resolução de DNS da rede
• Monitoring - Prometheus & Grafana
• APT Cache - Repositório de pacotes local (opcional)

Documentação

Começando

1. Introdução à Implantação Ansible
   • Vis��o geral de como o Ansible é usado para implantar redes celulares
   • Conceitos-chave: inventário, funções, playbooks, variáveis
   • Fluxo de trabalho de implantação e benefícios

Conceitos Principais

2. Padrão de Planejamento de IP

   • Arquitetura de rede e alocação de sub-rede
   • Modelo de implantação de quatro sub-redes
   • Diretrizes de atribuição de endereços IP
   • Tratamento de IPs públicos
   • Métodos de implementação (NICs separadas vs VLANs)

3. Configuração do Arquivo Hosts

   • Definindo sua topologia de rede
   • Configurando funções de rede e seus parâmetros
   • Entendendo a configuração PLMN
   • Trabalhando com templates Jinja2

4. Referência de Configuração

   • Guia completo para todas as variáveis de configuração
   • Configurações de componentes do OmniCore (HSS, PGW, SGW, DRA)
   • Configurações de componentes do OmniCall (TAS, Message, CSCF)
   • Configuração em tempo de execução explicada
   • Referência de variáveis com exemplos

5. Variáveis de Grupo e Configuração

   • Personalizando implantações sem modificar funções
   • Precedência e mesclagem de variáveis
   • Integração de templates Jinja2
   • Melhores práticas para substituições de configuração

Infraestrutura

6. Sistema de Cache APT

   • Opções de distribuição de pacotes (cache local vs repositório público)
   • Como pacotes pré-compilados são entregues
   • Configurando implantações offline/isoladas
   • Configuração de cache APT local

7. License Server

   • Gestão centralizada de licenças
   • Modelos de implantação (local, nuvem, híbrido)
   • Recursos controlados por licença
   • Alta disponibilidade e solução de problemas

• Configuração do Netplan - Configuração de rede/interface do host
• Implantação Proxmox - Provisionamento de VMs no Proxmox
• Playbooks de Serviço - Referência para os playbooks services/*.yml
• Replicação OmniHSS & Operações de Nó - Malha ativa-ativa, adição/semeadura de nós HSS, validação
• Firewall por Função - Modelo de fluxo, configuração de origem por site, modos de monitoramento/aplicação, matriz de portas

Observabilidade

• Registro Centralizado - Pipeline de agregação de logs
• Syslog de Dispositivo de Rede - Syslog de roteadores e dispositivos em Loki, rótulos de dispositivos, configuração do RouterOS
• Monitoramento & Observabilidade - Prometheus, Grafana e métricas

Utilitários

8. Playbooks de Utilidade
   • Verificação de Saúde: Gera relatórios HTML de saúde do sistema, status de serviços e versões
   • Usuários Comuns/Configuração: Configuração base do sistema e do usuário
   • Reboot: Reinicializações suaves do sistema
   • Gerador de Plano IP: Documentação da topologia da rede
   • Backup/Restaurar: services/backup.yml para backups, util_playbooks/restore_hss.yml para restaurar o HSS
   • Solução de Problemas: Recuperação de captura de pacotes, atualizações de MTU

Visão Completa

9. Visão Geral da Arquitetura de Implantação
   • Como todos os componentes se encaixam
   • Segmentação de rede e segurança
   • Dependências de serviços e ordem de implantação
   • Padrões de escalabilidade e alta disponibilidade

Início Rápido

Pré-requisitos

• Nó de controle Ubuntu 22.04+ (amd64)
• uv: necess��rio. Ele gerencia o ambiente Python e as dependências
• Python 3.12+ (uv pode instalar um interpretador adequado automaticamente)
• Acesso SSH aos hosts de destino
• Credenciais apropriadas para o repositório APT
• Licença Omnitouch válida

Instalação

1. Obtenha o Repositório

2. Instale uv se ainda não estiver instalado. Use o método que melhor se adequa ao seu nó de controle. Veja a documentação de instalação do uv. Por exemplo:

pipx install uv                                    # via pipx
curl -LsSf https://astral.sh/uv/install.sh | sh    # instalador autônomo

3. Instale o Ansible e as dependências. Isso cria um venv python.

No Ubuntu e Debian:

apt install libssh-dev
uv sync

No MacOS (usando brew):

brew install libssh
CFLAGS="-I $(brew --prefix)/include -I ext -L $(brew --prefix)/lib -lssh" uv sync

4. Ative o ambiente (mantenha-o ativado para todos os comandos ansible):

source .venv/bin/activate

5. Instale as coleções Ansible necessárias (do requirements.yml):

ansible-galaxy collection install -r requirements.yml

6. Verifique a instalação:

ansible --version

Linting

ansible-lint é executado no CI. Para executá-lo você mesmo:

uv sync --group lint            # instala ansible-lint (um grupo apenas para desenvolvedores, não incluído no .deb)
uv run ansible-lint [paths...]  # repositório inteiro, ou apenas os arquivos que você alterou

Configuração

1. Crie seu arquivo hosts com base no seu design de rede. Inventários de clientes vivem sob o diretório hosts/ de nível superior (services/hosts é um link simbólico para ele). Copie um exemplo existente como ponto de partida:

cp hosts/Omnicore_Omnitouch/host_files/yktn_Nick2.yml hosts/YourCustomer/host_files/production.yml

Veja: Configuração do Arquivo Hosts

2. Personalize com group_vars (opcional):

mkdir -p hosts/YourCustomer/group_vars
# Crie arquivos de personalização conforme necessário

Veja: Configuração de Variáveis de Grupo

3. Configure o acesso ao repositório APT em seu arquivo hosts:

Para implantações com um servidor de cache APT local (recomendado):

apt_cache_servers:
  hosts:
    your-apt-cache:
      ansible_host: 192.168.1.100
      gateway: 192.168.1.1

# Nenhuma configuração adicional necessária!
# use_apt_cache e apt_repo.apt_server são configurados automaticamente

Ou para acesso direto ao repositório:

all:
  vars:
    apt_repo:
      apt_server: "packages.omnitouch.com"
      apt_repo_username: "seu-usuario"
      apt_repo_password: "sua-senha"
    use_apt_cache: false  # Use repositório público diretamente (não cache)

Veja: Sistema de Cache APT

4. Configure o servidor de licença:

all:
  vars:
    license_server_api_urls: ["https://licenses.omnitouch.com/api"]
    license_enforced: true

Veja: License Server

Implantação

Implante sua rede completa:

# Implante toda a rede
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/all.yml

# Ou implante componentes específicos:
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/epc.yml
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/ims.yml

# Serviços de suporte são implantados via playbooks individuais (sem playbook de infra combinada):
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/dns.yml
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/monitoring.yml
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/license_server.yml
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/apt_cache.yml

Estrutura do Repositório

Omnicore/
├── README.md                    # Este arquivo
├── docs/                        # Documentação
│   ├── ansible-introduction.md
│   ├── IP_Planning_Standard.md
│   ├── hosts-file-configuration.md
│   ├── group-vars-configuration.md
│   ├── apt-cache-system.md
│   ├── license-server.md
│   ├── utility-playbooks.md     # Guia de playbooks de utilidade
│   ├── service-playbooks.md     # Guia de playbooks de serviço
│   └── deployment-architecture.md
├── hosts/                       # Inventários de clientes (nível superior)
│   └── Customer_Name/
│       ├── host_files/          # Arquivos de inventário
│       └── group_vars/          # Sobrescritas de variáveis
├── services/                    # Playbooks Ansible
│   ├── hosts -> ../hosts        # Link simbólico para hosts/ de nível superior
│   ├── epc.yml                  # Implantar núcleo 4G
│   ├── ims.yml                  # Implantar IMS
│   ├── omniss7.yml              # Implantar pilha SS7
│   ├── dns.yml                  # Implantar serviço de suporte DNS
│   ├── backup.yml               # Backup de bancos de dados principais
│   ├── all.yml                  # Implantar tudo
│   ├── common.yml               # Configuração base do sistema
│   ├── setup_users.yml          # Gerenciamento de usuários
│   ├── reboot.yml               # Utilitário de reinicialização suave
│   └── ...                      # Playbooks específicos de componentes
├── util_playbooks/              # Utilitários operacionais
│   ├── health_check.yml         # Relatório de saúde do sistema
│   ├── ip_plan_generator.yml    # Documentação de rede
│   ├── restore_hss.yml          # Restaurar HSS a partir de backup
│   ├── getLocalCapture.yml      # Recuperação de captura de pacotes
│   └── ...                      # Outros utilitários
├── roles/                       # Funções Ansible
│   ├── common/                  # Configuração base
│   ├── omnihss/                 # Implantação do OmniHSS
│   ├── omnisgwc/                # Implantação do OmniSGW
│   ├── omnipgwc/                # Implantação do OmniPGW
│   ├── applicationserver/       # OmniTAS (Servidor de Aplicações IMS)
│   ├── omnimessage/             # Implantação do OmniMessage
│   ├── license_server/          # Servidor de licença
│   ├── monitoring/              # Prometheus/Grafana
│   └── ...                      # Outras funções de componentes
├── packaging/                   # Configuração de build .deb (nfpm, build.sh)
├── .github/workflows/build-deb.yml  # CI build do omnicore .deb
├── requirements.yml             # Requisitos de coleção Ansible (ansible-galaxy)
├── pyproject.toml               # Dependências Python (uv)
└── uv.lock                      # Bloqueio de dependência Python fixo

OmniCore também pode ser instalado como um pacote .deb omnicore a partir do servidor APT. O pacote é construído por packaging/build.sh e .github/workflows/build-deb.yml.

Principais Recursos

Implantação Automatizada

• Rede celular completa implantada em horas
• Configuração consistente entre ambientes
• Implantações repetíveis para desenvolvimento, teste e produção

Configuração Flexível

• Templates Jinja2 para geração dinâmica de configuração
• group_vars para personalização específica do cliente
• Sem necessidade de modificar funções principais

Gerenciamento de Pacotes

• Pacotes binários pré-compilados (.deb)
• Cache APT local para implantações offline
• Repositório público para sites conectados à internet

Infraestrutura como Código

• Toda a configuração sob controle de versão Git
• Rastrear alterações e permitir rollback
• Revisar alterações antes da implantação

Playbooks Comuns

Playbook	Propósito
services/all.yml	Implantar rede completa
services/epc.yml	Implantar componentes EPC 4G
services/ims.yml	Implantar serviços de voz IMS
services/omniss7.yml	Implantar pilha SS7
services/dns.yml	Implantar serviço de suporte DNS
services/monitoring.yml	Implantar apenas monitoramento
services/license_server.yml	Implantar apenas servidor de licença
services/apt_cache.yml	Configurar cache APT local
util_playbooks/proxmox.yml	Criar VMs no Proxmox

Plataformas Suportadas

Hipervisores

• Proxmox VE
• VMware vSphere
• Instâncias em nuvem (Vultr / AWS / GCP)

Modelos de Implantação

• No local (data center do cliente)
• Nuvem (AWS, Azure, GCP via vLab)
• Híbrido (mistura de local e nuvem)
• Isolado (completamente offline)

---

Obtendo Ajuda

1. Verifique a documentação para guias detalhados
2. Revise exemplos de arquivos hosts para referência
3. Consulte a documentação do produto em https://docs.omnitouch.com.au/
4. Entre em contato com o suporte da Omnitouch para assistência na implantação

Próximos Passos

1. Leia a Introdução à Implantação Ansible
2. Revise o Padrão de Planejamento de IP para planejar sua arquitetura de rede
3. Revise a Visão Geral da Arquitetura de Implantação
4. Crie seu arquivo hosts
5. Personalize com group_vars conforme necessário
6. Implante sua rede!