namespace.yml

Descrição: este arquivo cria um Namespace no Kubernetes.

Um Namespace é usado para criar um escopo lógico de nomes dentro do cluster, permitindo separar recursos por projeto, sistema, ambiente, laboratório, disciplina, equipe ou finalidade.

Namespaces ajudam a organizar o cluster e permitem aplicar controles por escopo, como permissões, cotas, limites e políticas de rede. Eles não criam isolamento físico por si só; o isolamento real depende de outros recursos, como RBAC, ResourceQuota, LimitRange e NetworkPolicy.

No arquivo de referência do cluster, o recurso aparece como:

Recurso: namespaces
Tipo: Namespace
Versão: v1

TIPO:       Namespace
VERSÃO:    v1

DESCRIÇÃO:
    Namespace fornece um escopo para nomes. O uso de múltiplos namespaces é opcional.

Quando usar Namespace

Use Namespace quando você precisa separar recursos dentro do mesmo cluster.

Exemplos de separação:

por projeto;
por sistema;
por disciplina;
por laboratório;
por equipe;
por ambiente;
por aluno ou grupo de alunos;
por aplicação;
por homologação e produção;
por carga administrativa;
por carga acadêmica;
por carga de pesquisa.

Use Namespace quando:

vários projetos compartilham o mesmo cluster;
recursos precisam ser organizados;
permissões precisam ser separadas por grupo;
cada equipe deve ver ou alterar apenas seus próprios recursos;
cada ambiente precisa ter seus próprios Deployments, Services e Secrets;
você quer aplicar ResourceQuota;
você quer aplicar LimitRange;
você quer aplicar NetworkPolicy;
você quer aplicar RBAC por escopo;
você quer evitar conflito de nomes entre aplicações.

Exemplos comuns:

sistema-academico;
sistema-homologacao;
sistema-producao;
laboratorio-geologia;
disciplina-devops-2026;
projeto-pesquisa-x;
grupo-aluno-01;
monitoramento;
ingress-nginx;
argocd.

Quando Namespace não é o recurso indicado

Namespace não é o melhor recurso quando o problema exige outro tipo de controle.

Necessidade	Recurso mais indicado	Motivo
Executar aplicação	`Deployment`	Namespace apenas organiza recursos; ele não cria Pods.
Criar endereço interno estável para Pods	`Service`	Namespace não expõe aplicações.
Publicar aplicação por domínio HTTP/HTTPS	`Ingress`	Namespace não faz roteamento de entrada.
Guardar configuração	`ConfigMap`	Namespace não armazena configuração de aplicação.
Guardar senha/token	`Secret`	Namespace não armazena credenciais.
Controlar CPU/memória do namespace	`ResourceQuota` e `LimitRange`	Namespace sozinho não impõe limites de recursos.
Isolar tráfego entre aplicações	`NetworkPolicy`	Namespace sozinho não bloqueia tráfego de rede.
Definir permissões de usuários	`Role`, `RoleBinding`, `ClusterRole`, `ClusterRoleBinding`	Namespace sozinho não cria permissão.
Criar identidade para Pods	`ServiceAccount`	Namespace apenas contém ServiceAccounts.
Persistir dados	`PersistentVolumeClaim`	Namespace não fornece armazenamento.
Separar clusters fisicamente	Clusters diferentes	Namespace é isolamento lógico dentro do mesmo cluster.
Controlar segurança de Pods	Pod Security Admission, políticas ou admission controllers	Namespace pode receber labels de política, mas não aplica tudo sozinho.

Uso em cenário de universidade

Em uma universidade, um Namespace pode ser usado para organizar o cluster compartilhado entre sistemas institucionais, projetos acadêmicos, laboratórios, disciplinas, ambientes de homologação e aplicações de pesquisa.

Exemplos:

um namespace para um sistema administrativo;
um namespace para ambiente de homologação;
um namespace para ambiente de produção;
um namespace para cada laboratório;
um namespace para cada disciplina prática;
um namespace para cada grupo de alunos;
um namespace para cada projeto de pesquisa;
um namespace para ferramentas administrativas;
um namespace para GitOps;
um namespace para monitoramento.

Uso recomendado em ambiente universitário:

um Namespace por projeto, sistema, disciplina, laboratório ou ambiente;
ResourceQuota para limitar CPU, memória, Pods, Services, PVCs e outros objetos;
LimitRange para definir requests/limits padrão;
Role e RoleBinding para permissões dentro do namespace;
ServiceAccount com menor privilégio para aplicações;
NetworkPolicy para isolamento de tráfego;
ConfigMap para configuração não sensível;
Secret para credenciais;
Deployment para executar aplicações;
Service para expor Pods internamente;
Ingress para publicar aplicações HTTP/HTTPS;
labels padronizadas para classificar dono, ambiente e finalidade;
evitar colocar recursos de projetos diferentes no namespace default;
evitar dar permissão ampla de cluster para usuários que só precisam de um namespace.

Exemplo completo: namespace.yml

apiVersion: v1
kind: Namespace

metadata:
  name: meu-projeto
  labels:
    ambiente: homologacao
    finalidade: aplicacao
    tipo: projeto
  annotations:
    descricao: "Namespace exemplo para separar recursos de um projeto"

Explicação linha por linha

`apiVersion: v1`

Define a versão da API usada pelo manifesto.

Para Namespace, normalmente é:

apiVersion: v1

Significado:

v1: versão estável da API core do Kubernetes.

Use exatamente v1 para Namespace.

`kind: Namespace`

Define o tipo de recurso que será criado.

kind: Namespace

Significado:

Namespace: recurso que cria um escopo lógico de nomes dentro do cluster.

Não confundir com:

Deployment: cria e atualiza Pods;
Service: expõe Pods na rede;
Ingress: publica Services por HTTP/HTTPS;
ResourceQuota: limita recursos dentro do namespace;
LimitRange: define padrões e limites por objeto;
NetworkPolicy: controla tráfego entre Pods;
RoleBinding: concede permissões dentro do namespace.

`metadata`

metadata identifica e organiza o Namespace.

metadata:
  name: meu-projeto
  labels:
    ambiente: homologacao
  annotations:
    descricao: "Namespace exemplo"

`metadata.name`

Nome do Namespace.

name: meu-projeto

Uso:

identifica o namespace no cluster;
aparece em kubectl get namespaces;
é usado nos manifestos de recursos namespaced;
deve ser único no cluster.

Exemplos bons:

name: sistema-academico
name: sistema-homologacao
name: sistema-producao
name: laboratorio-geologia
name: disciplina-devops-2026
name: projeto-pesquisa-x
name: grupo-aluno-01

Regras práticas:

use letras minúsculas;
use hífen;
evite acentos;
evite espaços;
escolha nome curto e claro;
prefira nomes previsíveis e padronizados;
evite nomes genéricos demais, como teste, app ou novo.

`metadata.namespace`

O campo metadata.namespace aparece no kubectl explain porque faz parte de ObjectMeta, mas não deve ser usado para criar um Namespace.

Namespace é um recurso de escopo de cluster.

Ou seja:

metadata:
  name: meu-projeto

E não:

metadata:
  name: meu-projeto
  namespace: outro-namespace

Explicação:

recursos como Deployment, Service, ConfigMap e Secret ficam dentro de um namespace;
o próprio Namespace não fica dentro de outro namespace;
Kubernetes não possui namespaces aninhados.

`metadata.labels`

Labels são pares chave/valor usados para organização, seleção e políticas.

labels:
  ambiente: homologacao
  finalidade: aplicacao
  tipo: projeto

Uso:

organizar namespaces;
filtrar namespaces;
aplicar políticas por label;
associar namespace a ambiente ou finalidade;
permitir seleção por ferramentas de automação;
apoiar Pod Security Admission por labels de namespace.

Exemplo:

kubectl get namespaces -l ambiente=homologacao

Boas labels:

ambiente: producao
tipo: sistema
finalidade: aplicacao
responsavel: equipe-tecnica

Evite usar label com dado sensível.

Labels de Pod Security Admission

Namespaces podem receber labels para configurar níveis de Pod Security Admission, quando esse recurso está habilitado no cluster.

Exemplo:

metadata:
  labels:
    pod-security.kubernetes.io/enforce: baseline
    pod-security.kubernetes.io/audit: restricted
    pod-security.kubernetes.io/warn: restricted

Níveis comuns:

privileged
baseline
restricted

Uso:

restringir padrões de segurança de Pods no namespace;
gerar avisos ou auditoria;
impedir Pods com permissões excessivas.

Cuidado:

isso depende da configuração do cluster;
aplicar restricted pode bloquear aplicações que ainda não estão preparadas;
teste antes em homologação.

`metadata.annotations`

Annotations são metadados livres.

annotations:
  descricao: "Namespace do projeto"

Uso:

documentação;
rastreabilidade;
integração com ferramentas;
automações;
registrar finalidade do namespace.

Diferença entre labels e annotations:

Campo	Uso
`labels`	seleção, filtro e políticas
`annotations`	informação extra e documentação

Cuidado:

não coloque senha, token ou chave em annotation;
annotations também ficam armazenadas no objeto Kubernetes.

Campos de `metadata` normalmente gerenciados pelo Kubernetes

O kubectl explain mostra vários campos de metadata, mas muitos são preenchidos pelo próprio cluster.

Normalmente você não escreve manualmente:

creationTimestamp:
deletionTimestamp:
resourceVersion:
uid:
generation:
managedFields:
selfLink:

Eles servem para controle interno do Kubernetes.

`spec`

spec descreve detalhes do Namespace.

No arquivo de referência aparece:

spec:
  finalizers

Na maioria dos manifestos comuns, você não precisa declarar spec para Namespace.

Exemplo mais comum:

apiVersion: v1
kind: Namespace
metadata:
  name: meu-projeto

`spec.finalizers`

finalizers são mecanismos que impedem a remoção completa do Namespace até que certas limpezas sejam concluídas.

spec:
  finalizers:
    - kubernetes

Uso:

controle interno do Kubernetes;
garantir limpeza de recursos antes da remoção final;
impedir exclusão completa enquanto ainda há pendências.

Cuidado:

normalmente você não define manualmente spec.finalizers;
remover finalizers manualmente pode deixar recursos órfãos;
só mexa em finalizers em diagnóstico ou recuperação, sabendo exatamente o impacto.

`status`

status mostra o estado atual do Namespace.

Você normalmente não escreve status no YAML.

O Kubernetes preenche automaticamente.

No arquivo de referência aparecem campos como:

status:
  conditions
  phase

Use para diagnóstico:

kubectl get namespace meu-projeto -o yaml
kubectl describe namespace meu-projeto

`status.phase`

Mostra a fase atual do Namespace.

phase

Valores possíveis:

Active
Terminating

`Active`

O namespace está ativo e pode receber recursos.

Active

`Terminating`

O namespace está em processo de exclusão.

Terminating

Durante essa fase:

recursos dentro do namespace estão sendo removidos;
finalizers podem atrasar a exclusão;
objetos com finalizers pendentes podem travar a remoção.

`status.conditions`

Lista condições observadas no Namespace.

conditions:
  lastTransitionTime
  message
  reason
  status
  type

Uso:

diagnosticar namespace preso em Terminating;
identificar recursos restantes;
entender mensagens de finalização;
verificar problemas de descoberta de API durante exclusão.

Normalmente é somente leitura.

Manifesto mínimo funcional

apiVersion: v1
kind: Namespace
metadata:
  name: meu-projeto

Aplicar:

kubectl apply -f namespace.yml

Verificar:

kubectl get namespaces
kubectl get namespace meu-projeto

Manifesto recomendado para ambiente de projeto

apiVersion: v1
kind: Namespace
metadata:
  name: meu-projeto
  labels:
    ambiente: homologacao
    tipo: projeto
    finalidade: aplicacao
  annotations:
    descricao: "Namespace do projeto"

Este modelo é adequado para criar um namespace básico e organizado.

Manifesto recomendado com Pod Security Admission

apiVersion: v1
kind: Namespace
metadata:
  name: meu-projeto
  labels:
    ambiente: homologacao
    tipo: projeto
    finalidade: aplicacao
    pod-security.kubernetes.io/enforce: baseline
    pod-security.kubernetes.io/audit: restricted
    pod-security.kubernetes.io/warn: restricted
  annotations:
    descricao: "Namespace do projeto com labels de segurança de Pods"

Uso:

aplicar política de segurança de Pods por namespace;
gerar avisos para padrões mais restritivos;
preparar ambiente para controles mais rígidos.

Cuidado:

depende da configuração do cluster;
teste antes de aplicar em produção;
aplicações antigas podem precisar de ajustes.

Manifesto de namespace com conjunto recomendado ao redor

Um Namespace sozinho normalmente não é suficiente em ambiente compartilhado.

Exemplo de conjunto mínimo de governança:

Namespace
  ├── ResourceQuota
  ├── LimitRange
  ├── ServiceAccount
  ├── Role
  ├── RoleBinding
  └── NetworkPolicy

O Namespace cria o escopo.

Os outros recursos aplicam limites, permissões e isolamento.

Comandos úteis

Aplicar

kubectl apply -f namespace.yml

Ver Namespaces

kubectl get namespaces

Ver Namespace específico

kubectl get namespace meu-projeto

Ver detalhes

kubectl describe namespace meu-projeto

Ver YAML real aplicado

kubectl get namespace meu-projeto -o yaml

Criar namespace direto pelo kubectl

kubectl create namespace meu-projeto

Listar recursos de um namespace

kubectl get all -n meu-projeto

Listar ConfigMaps de um namespace

kubectl get configmaps -n meu-projeto

Listar Secrets de um namespace

kubectl get secrets -n meu-projeto

Listar permissões do usuário no namespace

kubectl auth can-i --list -n meu-projeto

Ver se pode criar Deployment no namespace

kubectl auth can-i create deployment -n meu-projeto

Definir namespace padrão no contexto atual

kubectl config set-context --current --namespace=meu-projeto

Ver namespace atual do contexto

kubectl config view --minify --output 'jsonpath={..namespace}'

Remover namespace

kubectl delete namespace meu-projeto

Cuidado:

Apagar um namespace remove os recursos namespaced dentro dele.

Relação com outros manifestos

Um Namespace normalmente é o primeiro recurso criado para um projeto ou ambiente.

Uso típico:

Namespace
  ├── ConfigMap
  ├── Secret
  ├── ServiceAccount
  ├── Role
  ├── RoleBinding
  ├── ResourceQuota
  ├── LimitRange
  ├── Deployment
  ├── Service
  ├── Ingress
  ├── NetworkPolicy
  └── PodDisruptionBudget

Namespace + Deployment

Namespace define onde o Deployment será criado.

Deployment executa os Pods da aplicação.

Namespace + Service

Namespace contém o Service.

Service expõe os Pods dentro daquele namespace.

Namespace + Ingress

Namespace contém o Ingress.

Ingress publica um Service do mesmo namespace.

Namespace + ConfigMap

Namespace separa configurações por projeto ou ambiente.

Namespace + Secret

Namespace separa credenciais por projeto ou ambiente.

Namespace + ResourceQuota

ResourceQuota limita uso total de recursos no namespace.

Namespace + LimitRange

LimitRange define padrões e limites para objetos criados no namespace.

Namespace + Role/RoleBinding

Role e RoleBinding concedem permissões dentro do namespace.

Namespace + NetworkPolicy

NetworkPolicy controla tráfego dos Pods dentro do namespace.

Erros comuns

Criar recursos no namespace errado

Sintoma:

Deployment foi criado;
Service não encontra endpoints;
ConfigMap ou Secret não é encontrado;
aplicação parece não existir no namespace esperado.

Verificar:

kubectl get all -A | grep minha-aplicacao

Correção:

declarar metadata.namespace nos manifestos namespaced;
ajustar contexto atual do kubectl;
padronizar namespaces por projeto.

Usar namespace `default` para tudo

Evite colocar todos os projetos no namespace default.

Problemas:

mistura recursos;
dificulta RBAC;
dificulta quotas;
dificulta auditoria;
dificulta limpeza;
aumenta risco de erro operacional.

Prefira:

um namespace por projeto, sistema, disciplina, laboratório ou ambiente

Achar que Namespace sozinho isola rede

Namespace organiza recursos, mas não bloqueia tráfego sozinho.

Para isolamento de rede, use:

NetworkPolicy

Achar que Namespace sozinho limita CPU e memória

Namespace não limita recursos sozinho.

Para limites, use:

ResourceQuota
LimitRange

Achar que Namespace sozinho cria permissão

Namespace não define quem pode acessar.

Para permissões, use:

Role
RoleBinding
ClusterRole
ClusterRoleBinding

Apagar namespace sem revisar conteúdo

Comando perigoso:

kubectl delete namespace meu-projeto

Isso remove recursos namespaced dentro dele.

Antes, revise:

kubectl get all -n meu-projeto
kubectl get configmaps,secrets,pvc,ingress,networkpolicy -n meu-projeto

Namespace preso em Terminating

Sintoma:

kubectl get namespace meu-projeto

Mostra:

Terminating

Possíveis causas:

recursos com finalizers;
APIs indisponíveis durante descoberta;
controladores ausentes;
objetos que não conseguem ser removidos.

Verificar:

kubectl describe namespace meu-projeto
kubectl get namespace meu-projeto -o yaml

Cuidado:

remover finalizers manualmente pode deixar resíduos;
faça diagnóstico antes de forçar remoção.

Tentar criar Namespace dentro de outro Namespace

Namespace é recurso de escopo de cluster.

Errado conceitualmente:

kind: Namespace
metadata:
  name: projeto-a
  namespace: setor-x

Correto:

kind: Namespace
metadata:
  name: projeto-a

Kubernetes não possui namespace dentro de namespace.

Checklist para uso em produção

Antes de aplicar um Namespace em ambiente compartilhado:

Resumo

Use Namespace para organizar recursos e criar escopos lógicos dentro do Kubernetes.

O Namespace controla:

escopo de nomes;
separação lógica de recursos;
base para RBAC namespaced;
base para quotas e limites;
base para políticas de rede;
organização por projeto, sistema, laboratório, disciplina ou ambiente.

Namespace sozinho não controla:

execução de aplicações;
rede;
permissões;
CPU/memória;
armazenamento;
publicação HTTP/HTTPS.

Para aplicação web comum, o conjunto mínimo geralmente é:

Namespace + Deployment + Service + Ingress

Para ambiente institucional compartilhado, o conjunto recomendado é:

Namespace + ResourceQuota + LimitRange + ServiceAccount + Role/RoleBinding
+ ConfigMap + Secret + Deployment + Service + Ingress + NetworkPolicy + PDB

Manifestos Kubernetes

namespace.yml

deployment.yml

service.yml

Ingress.yml

configmap.yml

secret.yml

pod.yml

persistentvolumeclaim.yml

persistentvolume.yml

GitLab-managed Kubernetes resources

Helm

Tutorial — Acessar o cluster Kubernetes pelo seu PC

namespace.yml

Quando usar Namespace

Quando Namespace não é o recurso indicado

Uso em cenário de universidade

Exemplo completo: namespace.yml

Explicação linha por linha

apiVersion: v1

kind: Namespace

metadata

metadata.name

metadata.namespace

metadata.labels

Labels de Pod Security Admission

metadata.annotations

Campos de metadata normalmente gerenciados pelo Kubernetes

spec

spec.finalizers

status

status.phase

Active

Terminating

status.conditions

Manifesto mínimo funcional

Manifesto recomendado para ambiente de projeto

Manifesto recomendado com Pod Security Admission

Manifesto de namespace com conjunto recomendado ao redor

Comandos úteis

Aplicar

Ver Namespaces

Ver Namespace específico

Ver detalhes

Ver YAML real aplicado

Criar namespace direto pelo kubectl

Listar recursos de um namespace

Listar ConfigMaps de um namespace

Listar Secrets de um namespace

Listar permissões do usuário no namespace

Ver se pode criar Deployment no namespace

Definir namespace padrão no contexto atual

Ver namespace atual do contexto

Remover namespace

Relação com outros manifestos

Namespace + Deployment

Namespace + Service

Namespace + Ingress

Namespace + ConfigMap

Namespace + Secret

Namespace + ResourceQuota

Namespace + LimitRange

Namespace + Role/RoleBinding

Namespace + NetworkPolicy

Erros comuns

Criar recursos no namespace errado

Usar namespace default para tudo

Achar que Namespace sozinho isola rede

Achar que Namespace sozinho limita CPU e memória

Achar que Namespace sozinho cria permissão

Apagar namespace sem revisar conteúdo

Namespace preso em Terminating

Tentar criar Namespace dentro de outro Namespace

Checklist para uso em produção

Resumo

`apiVersion: v1`

`kind: Namespace`

`metadata`

`metadata.name`

`metadata.namespace`

`metadata.labels`

`metadata.annotations`

Campos de `metadata` normalmente gerenciados pelo Kubernetes

`spec`

`spec.finalizers`

`status`

`status.phase`

`Active`

`Terminating`

`status.conditions`

Usar namespace `default` para tudo